Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Relational recall arm (typed-edge retrieval, v0.43).
*
* Turns a relational query into a ranked list of edge-derived candidates that
* hybridSearch injects as a FOURTH RRF arm (alongside keyword + vector), so a
* relationship answer competes for ranking instead of relying on lexical or
* vector similarity to surface it.
*
* Flow: parseRelationalQuery → resolve seed entity(ies) (scope-aware,
* confidence-gated) → engine.relationalFanout (within-source, deterministic)
* → batch-hydrate to SearchResult rows (reinforcing each page's REAL canonical
* chunk; page-level key for chunkless entity pages).
*
* Determinism: parses the ORIGINAL query (never an LLM-expanded variant);
* traversal + resolution are deterministic. Fail-open: any error returns an
* empty arm + an audit row, never breaking the search hot path.
*
* Federation (E2=A): resolves the seed in every in-scope source and fans out
* from each; traversal stays WITHIN each source (no cross-boundary edges in
* v1). Confidence gate (D3): a seed that only `fallback_slugify`-resolves is
* dropped, so the arm never traverses from an invented slug. The tier-2
* resolution-margin gate is a filed TODO.
*
* Tested in test/relational-recall.test.ts.
*/
import type { BrainEngine } from '../engine.ts';
import type { SearchResult, PageType, RelationalFanoutRow, PageReadPolicy } from '../types.ts';
import { createAuditWriter } from '../audit/audit-writer.ts';
import { listSources } from '../sources-ops.ts';
import { ALL_SOURCES } from '../source-id.ts';
import { resolveEntitySlugWithSource, retiredPageSql } from '../entities/resolve.ts';
import { buildVisibilityClause } from './sql-ranking.ts';
import { hasReadPolicy, pageReadFilter } from './read-policy-sql.ts';
import { boundedProjectedPrefix } from '../page-window/document.ts';
import { boundedBodyPrefixSql, overlaidBoundedRows } from '../page-window/bounded-lead.ts';
import { parseRelationalQuery, type RelationalQuery, type RelationVocab } from './relational-intent.ts';
import { edgeValidityEnabled, type EdgeTemporalOpts } from '../link-validity.ts';
import { stampEvidence, type EvidenceOpts } from './evidence.ts';
import { parseRelationalPlan } from './relational-plan.ts';
import { chainStoredEdge, LINK_SIGNATURES, presentEdgeContext, resolveChainAnchors, runRelationalChain, type ChainAnchor, type ChainDiagnostics, type ChainStatus, type RelationalChainRow } from './relational-chain.ts';
import { worldLinkContexts } from '../eligibility/fence-overlay.ts';
import { requiresSafeChunks } from './safe-chunks.ts';
export interface RelationalArmOpts extends PageReadPolicy {
sourceId?: string;
sourceIds?: string[];
depth?: number;
limit?: number;
vocab?: RelationVocab;
/**
* #4352 remediation — hide `visibility: private` pages from the arm's
* hydrated candidates. hybridSearch threads the caller's resolved gate
* (resolveExcludePrivatePages) here, same as the keyword/vector arms;
* without it a remote relational query leaked private titles + snippets.
*/
excludePrivate?: boolean;
/** Multi-relation questions walk typed hop chains (search.relational_planner). */
planner?: boolean;
/** Typed one-hop walks also read edges written on the other page (search.relational_orient_onehop). */
orientOneHop?: boolean;
onMeta?: (meta: RelationalArmMeta) => void;
}
export interface RelationalArmMeta {
fired: boolean;
kind: RelationalQuery['kind'] | 'chain' | null;
seeds_resolved: number;
candidates: number;
errored: boolean;
duration_ms: number;
/** Multi-relation plan outcome, when the planner ran on a 2-3 relation question. */
plan?: RelationalPlanMeta;
}
export interface RelationalPlanMeta {
status: ChainStatus | 'unsupported';
reason?: string;
anchor?: string;
anchor_slugs?: string[];
hops?: Array<{ link_types: string[]; toward: 'object' | 'subject'; frontier: number; edges: number }>;
answers?: number;
cap_hit?: ChainDiagnostics['cap_hit'];
empty_hop?: number;
}
interface RelationalFailureEvent {
ts: string;
error_summary: string;
query_kind: string;
}
const failureWriter = createAuditWriter<RelationalFailureEvent>({
featureName: 'relational-recall-failures',
errorLabel: 'gbrain',
errorTrailer: '; search continues',
});
/** Recent relational-arm fail-open events — consumed by doctor + search stats. */
export function readRecentRelationalFailures(days = 7, now: Date = new Date()): RelationalFailureEvent[] {
return failureWriter.readRecent(days, now);
}
function truncate(msg: string, max = 200): string {
return msg.length <= max ? msg : msg.slice(0, max - 1) + '…';
}
/** Sources to resolve a seed against. Federated → the set; scalar → [id].
*
* Unscoped (trusted local; the `query` op resolves `__all__` to unscoped for
* local callers) → every non-archived source. The prior `['default']`
* fallback made `--source-id __all__` a shipped-contract bug on multi-source
* brains: the keyword and vector arms spanned every source while this arm
* answered from `default` alone. Cost: one resolver chain per non-archived
* source. Traversal is still WITHIN each seed's source (E2=A) — only seed
* RESOLUTION widens here, never the walk.
*
* A literal `__all__` that reaches this arm comes from a caller whose scope
* was NOT resolved by a trusted-local path, so it must stay fail-closed:
* resolve no seeds (the arm no-ops) rather than widen to every source. */
async function scopeSources(engine: BrainEngine, opts: RelationalArmOpts): Promise<string[]> {
if (opts.sourceIds && opts.sourceIds.length > 0) return opts.sourceIds;
if (opts.sourceId === ALL_SOURCES) return [];
if (opts.sourceId) return [opts.sourceId];
const sources = await listSources(engine);
return sources.map(s => s.id);
}
/** Page types a relation's seed may be besides an entity. The entity resolver
* never returns a meeting, so "Who attended <meeting title>?" needs its own
* exact-title tier. */
function titleSeedTypes(parsed: RelationalQuery): string[] {
return parsed.direction === 'in' && parsed.linkTypes?.includes('attended') ? ['meeting', 'event'] : [];
}
/** Resolve a seed phrase to all in-scope (source_id, slug) pairs that
* resolve to a REAL page (confidence gate D3 tier-1: drop fallback_slugify).
* When the entity resolver only slugifies, a live page of one of
* `titleTypes` whose title is exactly the phrase (case-insensitive, unique in
* the source) is the seed. */
async function resolveSeedScoped(
engine: BrainEngine,
sources: string[],
phrase: string,
policy: PageReadPolicy,
titleTypes: string[] = [],
): Promise<Array<{ source_id: string; slug: string }>> {
const out: Array<{ source_id: string; slug: string }> = [];
const seen = new Set<string>();
for (const sid of sources) {
let r = await resolveEntitySlugWithSource(engine, sid, phrase);
if (r?.source === 'fallback_slugify' && titleTypes.length) {
const titled = await engine.executeRaw<{ slug: string }>(
`SELECT slug FROM pages WHERE source_id = $1 AND deleted_at IS NULL AND type = ANY($2::text[])
AND lower(title) = lower($3) AND NOT ${retiredPageSql('pages')} LIMIT 2`, [sid, titleTypes, phrase.trim()]);
if (titled.length === 1) r = { slug: titled[0].slug, source: 'exact_page' };
}
if (!r || r.source === 'fallback_slugify') continue;
const key = `${sid}:${r.slug}`;
if (seen.has(key)) continue;
seen.add(key);
out.push({ source_id: sid, slug: r.slug });
}
if (!out.length || !hasReadPolicy(policy)) return out;
const params: unknown[] = [out.map(ref => ref.source_id), out.map(ref => ref.slug)];
const filter = pageReadFilter('p', policy, params, true);
const admitted = await engine.executeRaw<{ source_id: string; slug: string }>(
`SELECT p.source_id, p.slug FROM pages p
JOIN unnest($1::text[], $2::text[]) AS refs(source_id, slug)
ON p.source_id = refs.source_id AND p.slug = refs.slug WHERE ${filter}`, params,
);
const allowed = new Set(admitted.map(ref => `${ref.source_id}:${ref.slug}`));
return out.filter(ref => allowed.has(`${ref.source_id}:${ref.slug}`));
}
/** Batch-hydrate fanout rows into SearchResult rows in fanout (ranked) order.
* #4352 remediation: the SELECT surfaces titles + compiled_truth snippets, so
* it applies the full shared visibility clause (deleted + archived-source +
* quarantine, plus the private predicate when excludePrivate) — pre-fix it
* filtered on deleted_at alone and leaked private/archived pages. */
async function hydrate(
engine: BrainEngine,
rows: RelationalFanoutRow[],
seedSlug: string,
policy: PageReadPolicy,
): Promise<SearchResult[]> {
if (rows.length === 0) return [];
const params: unknown[] = [rows.map(r => r.source_id), rows.map(r => r.slug)];
const filter = pageReadFilter('p', policy, params);
const pageRows = await engine.executeRaw<{
page_id: number; slug: string; source_id: string; title: string; type: string; synopsis: string | null;
}>(
`SELECT p.id AS page_id, p.slug, p.source_id, p.title, p.type,
${boundedBodyPrefixSql('p')} AS synopsis
FROM pages p
JOIN sources s ON s.id = p.source_id
JOIN unnest($1::text[], $2::text[]) AS refs(source_id, slug)
ON p.source_id = refs.source_id AND p.slug = refs.slug
WHERE ${filter} ${buildVisibilityClause('p', 's', { excludePrivate: policy.excludePrivate, requireSafeChunks: false })}`,
params,
);
// Large pages: a bounded, withdrawal-overlaid prefix per row is sanitized, never the whole body.
const leads = await overlaidBoundedRows(engine, pageRows.map(pr => ({ slug: pr.slug, source_id: pr.source_id, compiled_truth: pr.synopsis })));
const byKey = new Map<string, typeof pageRows[number]>();
pageRows.forEach((pr, i) => byKey.set(`${pr.source_id}:${pr.slug}`, { ...pr, synopsis: leads[i].compiled_truth }));
const out: SearchResult[] = [];
for (const r of rows) {
const pr = byKey.get(`${r.source_id}:${r.slug}`);
if (!pr) continue;
out.push({
slug: r.slug,
page_id: pr.page_id,
title: pr.title,
type: pr.type as PageType,
chunk_text: boundedProjectedPrefix(pr.synopsis ?? r.slug).slice(0, 240),
chunk_source: 'compiled_truth',
// E1: reinforce the page's REAL canonical chunk; F3: chunkless entity
// pages key page-level (chunk_id 0 → rrfKey `source:slug:0`, stable and
// collision-safe; SERIAL chunk ids start at 1 so 0 never aliases a real chunk).
chunk_id: r.canonical_chunk_id ?? 0,
chunk_index: 0,
score: 0, // rank-based: RRF derives score from list position
stale: false,
source_id: r.source_id,
relational_via_link_types: r.via_link_types,
relational_seed: seedSlug,
relational_hop: r.hop,
relational_path: r.path,
relational_path_edges: r.path_edges,
});
}
return out;
}
/**
* Rows that may claim a relational guarantee (pin, page-1 slot): one-hop rows
* and chain answers. A chain's intermediate or origin page is evidence, not an
* answer, so it never satisfies a guarantee meant for the answer.
*/
export function answerRows(list: readonly SearchResult[]): SearchResult[] {
return list.filter(r => r.relational === undefined || r.relational.role === 'answer');
}
/**
* #3995 — decision stamp for the guaranteed page-1 relational evidence slot.
* Surfaced through HybridSearchMeta.relational_evidence_slot so `--explain`
* consumers can audit why a low-fused-score row appears on the first page.
*/
export interface RelationalEvidenceSlotDecision {
action: 'promoted' | 'injected' | 'chain_pinned';
/** chain_pinned only: how many chain rows were placed at the top of page 1. */
count?: number;
slug: string;
source_id: string;
/** promoted only: the 0-based fused rank the row was lifted from. */
from_rank?: number;
}
/**
* #3995 — guarantee page-1 evidence for a FIRED relational arm.
*
* A relational answer is often lexically unrecoverable (unverified entity
* stub, single-arm RRF score), so the fused row can land beyond the `limit`
* slice (fusion overflow) or be dropped entirely by autocut (which only
* preserves alias hits). When the arm fired, at least one of its pages must
* survive to the first page or the feature silently no-ops.
*
* Pure (returns a new array; never mutates inputs). Page-level check on
* `(source_id, slug)`:
* - some relational page already in the top-`limit` window → no-op;
* - best-ranked fused relational row sits beyond the window → PROMOTE it
* into slot `limit-1` (keeps its real fused score);
* - no relational page in the pool at all (autocut/trim dropped it) →
* INJECT `relationalList[0]` at slot `limit-1` (score clamped just below
* its new predecessor so ordering stays monotone).
*
* First page only: `offset > 0` is a pure no-op (paginating a guaranteed
* slot is incoherent — the row would repeat on every page).
*/
export function ensureRelationalEvidenceSlot(
pool: SearchResult[],
relationalList: SearchResult[],
limit: number,
offset: number,
evidenceOpts?: EvidenceOpts,
chainSlots = 0,
): { pool: SearchResult[]; decision?: RelationalEvidenceSlotDecision } {
if (chainSlots > 0 && offset === 0) {
const pinned = pinChainRows(pool, relationalList, Math.min(chainSlots, limit), evidenceOpts);
if (pinned) return pinned;
}
relationalList = answerRows(relationalList);
if (offset > 0 || limit <= 0 || relationalList.length === 0) return { pool };
const pageKey = (r: SearchResult) => `${r.source_id ?? 'default'}:${r.slug}`;
const relKeys = new Set(relationalList.map(pageKey));
const window = Math.min(limit, pool.length);
for (let i = 0; i < window; i++) {
if (relKeys.has(pageKey(pool[i]))) return { pool }; // evidence already on page 1
}
// Fusion overflow: the arm's best fused row survived ranking but sits past
// the slice boundary — promote it into the last page-1 slot.
for (let i = limit; i < pool.length; i++) {
if (!relKeys.has(pageKey(pool[i]))) continue;
const out = pool.slice();
const [row] = out.splice(i, 1);
out.splice(limit - 1, 0, row);
return {
pool: out,
decision: { action: 'promoted', slug: row.slug, source_id: row.source_id ?? 'default', from_rank: i },
};
}
// Dropped entirely (autocut / trim): re-inject the arm's top candidate.
const out = pool.slice();
const insertAt = Math.min(limit - 1, out.length);
const prev = insertAt > 0 ? out[insertAt - 1] : undefined;
const top = relationalList[0];
// Clamp just below the predecessor when the raw arm score is non-positive
// OR would exceed it — the returned page must stay monotone.
const row =
prev && (!(top.score > 0) || top.score > prev.score)
? { ...top, score: Math.max(0, prev.score * 0.999) }
: { ...top };
// The injected row is a raw arm row that never saw the pipeline's
// stampEvidence pass (which runs before this slot) — stamp it here so every
// page-1 row carries the evidence/create_safety contract.
stampEvidence([row], evidenceOpts);
out.splice(insertAt, 0, row);
return {
pool: out,
decision: { action: 'injected', slug: row.slug, source_id: row.source_id ?? 'default' },
};
}
/**
* Chain slots: when a multi-hop chain fired, its rows (answers first, then the
* evidence pages of their paths, in arm order) take the top of page 1, up to
* `slots`. A chain answer is exact typed evidence for the question while the
* lexical rows of a relationship question mostly match names, so the chain
* leads; the rest of the pool follows in its own order. Returns null when no
* chain fired (the single evidence slot then applies).
*/
function pinChainRows(
pool: SearchResult[],
relationalList: SearchResult[],
slots: number,
evidenceOpts?: EvidenceOpts,
): { pool: SearchResult[]; decision: RelationalEvidenceSlotDecision } | null {
const chain = relationalList.filter(r => r.relational !== undefined).slice(0, slots);
if (chain.length === 0) return null;
const pageKey = (r: SearchResult) => `${r.source_id ?? 'default'}:${r.slug}`;
const inPool = new Map<string, SearchResult>();
for (const r of pool) if (!inPool.has(pageKey(r))) inPool.set(pageKey(r), r);
const keys = new Set(chain.map(pageKey));
const top = chain.map(r => {
const fused = inPool.get(pageKey(r));
if (fused) return { ...fused, relational: fused.relational ?? r.relational };
const raw = { ...r };
stampEvidence([raw], evidenceOpts);
return raw;
});
const lead = pool[0]?.score ?? 0;
const ordered = top.map((r, i) => ({ ...r, score: Math.max(r.score, lead) + (top.length - i) * 1e-6 }));
return {
pool: [...ordered, ...pool.filter(r => !keys.has(pageKey(r)))],
decision: { action: 'chain_pinned', slug: chain[0].slug, source_id: chain[0].source_id ?? 'default', count: chain.length },
};
}
/**
* Build the relational recall arm. Returns an empty list (pure no-op) when the
* query isn't relational or no seed resolves. Never throws.
*/
export async function buildRelationalArm(
engine: BrainEngine,
query: string,
opts: RelationalArmOpts = {},
): Promise<SearchResult[]> {
const startedAt = Date.now();
const meta: RelationalArmMeta = {
fired: false, kind: null, seeds_resolved: 0, candidates: 0, errored: false, duration_ms: 0,
};
const finish = (list: SearchResult[]) => {
meta.candidates = list.length;
meta.duration_ms = Date.now() - startedAt;
opts.onMeta?.(meta);
return list;
};
if (opts.planner) {
const planned = await planChain(engine, query, opts, meta);
if (planned === 'unsupported') return finish([]);
if (planned) return finish(planned);
}
const parsed = parseRelationalQuery(query, opts.vocab);
if (!parsed) return finish([]);
meta.kind = parsed.kind;
try {
const sources = await scopeSources(engine, opts);
const temporal = await edgeValidityEnabled(engine) ? { status: parsed.edgeStatus } : undefined;
const fanoutOpts = {
temporal,
sourceId: opts.sourceId,
sourceIds: opts.sourceIds,
excludePrivate: opts.excludePrivate,
requireSafeChunks: opts.requireSafeChunks,
takesHoldersAllowList: opts.takesHoldersAllowList,
minTrust: opts.minTrust,
suppressFlagged: opts.suppressFlagged,
linkTypes: parsed.linkTypes,
direction: parsed.direction,
depth: opts.depth,
limit: opts.limit,
};
if (parsed.kind === 'connects' && parsed.seeds.length === 2) {
// Resolve both endpoints; both must resolve or the arm no-ops.
const resA = await resolveSeedScoped(engine, sources, parsed.seeds[0], opts);
const resB = await resolveSeedScoped(engine, sources, parsed.seeds[1], opts);
if (resA.length === 0 || resB.length === 0) return finish([]);
meta.seeds_resolved = resA.length + resB.length;
const a = { slugs: [...new Set(resA.map(ref => ref.slug))], seedRefs: resA };
const b = { slugs: [...new Set(resB.map(ref => ref.slug))], seedRefs: resB };
const fanA = await engine.relationalFanout(a.slugs, { ...fanoutOpts, seedRefs: a.seedRefs });
const fanB = await engine.relationalFanout(b.slugs, { ...fanoutOpts, seedRefs: b.seedRefs });
// Shared midpoints: nodes reachable from BOTH endpoints (exclude the
// endpoints themselves). Ordered by combined hop.
const bByKey = new Map(fanB.map(r => [`${r.source_id}:${r.slug}`, r] as const));
const endpointSlugs = new Set([...a.slugs, ...b.slugs]);
const shared = fanA
.filter(r => bByKey.has(`${r.source_id}:${r.slug}`) && !endpointSlugs.has(r.slug))
.map(r => ({ row: r, combined: r.hop + bByKey.get(`${r.source_id}:${r.slug}`)!.hop }))
.sort((x, y) => x.combined - y.combined || x.row.slug.localeCompare(y.row.slug))
.map(x => x.row);
const list = await hydrate(engine, shared, parsed.seeds.join(' ↔ '), opts);
meta.fired = list.length > 0;
return finish(list);
}
// who_rel / who_at / intro: single logical seed (may resolve in N sources).
const resolved = await resolveSeedScoped(engine, sources, parsed.seeds[0], opts, titleSeedTypes(parsed));
if (resolved.length === 0) return finish([]);
meta.seeds_resolved = resolved.length;
const slugs = Array.from(new Set(resolved.map(r => r.slug)));
let rows = await engine.relationalFanout(slugs, {
...fanoutOpts,
seedRefs: resolved,
});
if (opts.orientOneHop && parsed.kind === 'who_rel' && parsed.direction !== 'both'
&& parsed.linkTypes?.length && parsed.linkTypes.every(lt => LINK_SIGNATURES[lt])) {
rows = await withOrientedOneHop(engine, rows, resolved, parsed, temporal ? { ...opts, temporal } : opts);
}
const list = await hydrate(engine, rows, resolved[0].slug, opts);
meta.fired = list.length > 0;
return finish(list);
} catch (err) {
const msg = err instanceof Error ? err.message : String(err);
failureWriter.log({ error_summary: truncate(msg), query_kind: parsed.kind });
meta.errored = true;
return finish([]);
}
}
/**
* Multi-relation questions: plan, resolve the anchor, walk the chain, hydrate.
* Returns the arm list when the chain found answers; `null` when the planner
* does not apply or the chain found nothing (the one-hop path then runs as
* before, so a plan can never remove a one-hop answer); `'unsupported'` when
* the question chains relations in a way the planner refuses (coordination,
* negation, time): no relational arm then, never a one-hop guess.
*/
async function planChain(
engine: BrainEngine,
query: string,
opts: RelationalArmOpts,
meta: RelationalArmMeta,
): Promise<SearchResult[] | null | 'unsupported'> {
const result = parseRelationalPlan(query);
if (result.kind === 'not_applicable') return null;
meta.kind = 'chain';
if (result.kind === 'unsupported') {
meta.plan = { status: 'unsupported', reason: result.reason };
return 'unsupported';
}
const { plan } = result;
try {
const sources = await scopeSources(engine, opts);
const refs = await resolveSeedScoped(engine, sources, plan.anchor, opts);
const anchors: ChainAnchor[] = [];
for (const ref of refs) anchors.push(...await resolveChainAnchors(engine, ref.slug, { ...opts, sourceIds: undefined, sourceId: ref.source_id }));
meta.seeds_resolved = anchors.length;
// Live relationships by default; a tense marker on one relation ("formerly advised") sets that hop's status.
const temporal = await edgeValidityEnabled(engine) ? { status: 'live' as const } : undefined;
const { rows, diagnostics } = await runRelationalChain(engine, anchors, { hops: plan.hops, excludeAnchor: plan.excludeAnchor }, temporal ? { ...opts, temporal } : opts);
meta.plan = {
status: diagnostics.status, anchor: plan.anchor, anchor_slugs: anchors.map(a => a.slug),
hops: diagnostics.per_hop, answers: rows.filter(r => r.role === 'answer').length,
...(diagnostics.cap_hit ? { cap_hit: diagnostics.cap_hit } : {}),
...(diagnostics.empty_hop ? { empty_hop: diagnostics.empty_hop } : {}),
};
if (rows.length === 0) return null;
const list = await hydrateChain(engine, rows, anchors, opts);
meta.fired = list.length > 0;
return list.length > 0 ? list : null;
} catch (err) {
const msg = err instanceof Error ? err.message : String(err);
failureWriter.log({ error_summary: truncate(msg), query_kind: 'chain' });
meta.errored = true;
return null;
}
}
/** Answers first (up to the arm limit), then the evidence pages on their retained paths while room remains. */
async function hydrateChain(
engine: BrainEngine,
rows: RelationalChainRow[],
anchors: ChainAnchor[],
opts: RelationalArmOpts,
): Promise<SearchResult[]> {
const limit = Math.max(1, opts.limit ?? 50);
const picked = rows.slice(0, limit);
const fanoutShaped: RelationalFanoutRow[] = picked.map(r => ({
source_id: r.source_id, slug: r.slug, hop: r.hop, edge_count: r.path_count,
via_link_types: [...new Set(r.best_path.edges.map(e => e.link_type))], path: r.best_path.nodes,
canonical_chunk_id: r.canonical_chunk_id,
}));
const seed = anchors[0]?.slug ?? '';
const hydrated = await hydrate(engine, fanoutShaped, seed, opts);
const remote = requiresSafeChunks(opts);
const byKey = new Map(picked.map(r => [`${r.source_id}:${r.slug}`, r] as const));
const shown = hydrated.map(h => byKey.get(`${h.source_id}:${h.slug}`)!);
const contexts = (await worldLinkContexts(engine, remote,
shown.flatMap(r => r.best_path.edges.slice(-3).map(e => ({ ...e, source_id: r.source_id }))), chainStoredEdge)).map(e => e.context);
let next = 0;
return hydrated.map((h, i) => {
const r = shown[i]!;
return {
...h,
relational: {
role: r.role, seed, hop: r.hop, path_count: r.path_count,
edges: r.best_path.edges.slice(-3).map(e => ({ ...e, context: presentEdgeContext(contexts[next++] ?? null, remote) })),
},
};
});
}
/**
* Typed one-hop orientation: add the neighbors a relation reaches through
* edges written on the other page (a company page saying "founded by X"),
* after the stored-direction hop-1 rows and before deeper rows.
*/
async function withOrientedOneHop(
engine: BrainEngine,
rows: RelationalFanoutRow[],
seeds: Array<{ source_id: string; slug: string }>,
parsed: RelationalQuery,
opts: RelationalArmOpts & { temporal?: EdgeTemporalOpts },
): Promise<RelationalFanoutRow[]> {
const anchors: ChainAnchor[] = [];
for (const s of seeds) anchors.push(...await resolveChainAnchors(engine, s.slug, { ...opts, sourceIds: undefined, sourceId: s.source_id }));
const toward = parsed.direction === 'in' ? 'subject' : 'object';
const { rows: chain } = await runRelationalChain(engine, anchors, { hops: [{ linkTypes: parsed.linkTypes!, toward }], excludeAnchor: true }, opts);
const have = new Set(rows.map(r => `${r.source_id}:${r.slug}`));
const extra: RelationalFanoutRow[] = chain
.filter(r => r.role === 'answer' && !have.has(`${r.source_id}:${r.slug}`))
.map(r => ({
source_id: r.source_id, slug: r.slug, hop: 1, edge_count: 1, via_link_types: [...parsed.linkTypes!],
path: r.best_path.nodes, canonical_chunk_id: r.canonical_chunk_id,
}));
if (extra.length === 0) return rows;
const hop1 = rows.filter(r => r.hop <= 1);
return [...hop1, ...extra, ...rows.filter(r => r.hop > 1)].slice(0, Math.max(rows.length, opts.limit ?? 50));
}