Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Facts arm for `query` (`search.query_facts_arm`, default on; gates in
* docs/eval/decisions/query-facts-arm/). A correction saved with `remember`
* lives in the facts table, which page search never ranks, so the stale page
* text answers instead. Unless the key is off, `query` adds the active facts that
* match the question as rows of their own, inside the caller's row count and
* token budget, and stamps a page row `superseded_claim` when a newer active
* fact covers the same entity and typed claim slot as a fact taken from that
* page.
*
* Matching: query terms against the fact text and entity (at least half of
* the content terms), cosine against the query embedding hybrid search
* already computed (no extra model call; skipped when there is none), and the
* facts of the one entity page the query names (in that page's source); the
* candidate pool is fact-relevance.ts's. Matches are ordered newest
* valid_from first. Read policy is recall's: source scope, active rows only,
* audit rows excluded, and world-visible facts with non-private provenance
* for remote callers.
*/
import type { BrainEngine } from '../engine.ts';
import type { PageReadScope, SearchResult } from '../types.ts';
import { resolveExcludePrivatePages, worldOnlyFacts } from './private-visibility.ts';
import { admitted, collectFactCandidates, FACTS_ARM_COSINE_MIN, laterRetractions, queryTerms, scoreFactCandidates, type FactCandidate as PoolCandidate, type FactPoolScope } from './fact-relevance.ts';
import { readSlotHistory, slotWindows } from './slot-history.ts';
import { pageReadFilter } from './read-policy-sql.ts';
import { enforceTokenBudget, resultTokens } from './token-budget.ts';
import { configFlagOn, factDateHeader, factObservationDates } from './evidence-date.ts';
import { collapseFactReads } from '../facts/capture-dedup.ts';
import type { TrustTier } from '../trust/tier.ts';
import { conversationSignal } from './evidence-delivery.ts';
import { factsFromQuotedPages } from './transcript-quote.ts';
import { findTimeMentions } from '../temporal-grammar.ts';
import { withDecideContested, type ContestedLookup } from '../facts/contested-claims.ts';
import type { Contested } from '../eligibility/labels.ts';
export { queryTerms } from './fact-relevance.ts';
export const QUERY_FACTS_ARM_KEY = 'search.query_facts_arm';
/** Fact rows added per query at most. */
export const MAX_FACT_ROWS = 3;
/** Cosine similarity a fact needs against the query embedding to count as a match on its own. */
export const FACT_COSINE_MIN = FACTS_ARM_COSINE_MIN;
/** Share of the query's content terms a fact's text and entity must hold to match by keyword. */
const TERM_SHARE_MIN = 0.5;
/** Temporal fact reserve (docs/eval/decisions/temporal-fact-reserve/): off by default. */
export const TEMPORAL_FACT_RESERVE_KEY = 'search.temporal_fact_reserve';
/** Share of the caller's token budget reserved facts may take. */
export const TEMPORAL_RESERVE_SHARE = 0.15;
export const MAX_RESERVE_ROWS = 20;
/** Share of the caller's row count reserved facts may take (at least one row). */
export const TEMPORAL_RESERVE_ROW_SHARE = 0.3;
/** GBRA-205 facts block (`search.query_facts_block`, default on): every query with a caller token budget, ahead of the pages. */
export const QUERY_FACTS_BLOCK_KEY = 'search.query_facts_block';
/** Share of the caller's token budget the facts block may take (about 1,800 of 8,100, as the measured combined lane). */
export const QUERY_FACTS_BLOCK_SHARE = 0.22;
export const MAX_FACTS_BLOCK_ROWS = 40;
/** GBRA-205 (`search.fact_source_pages`, default off): the conversations matched facts came from join the hits. */
export const FACT_SOURCE_PAGES_KEY = 'search.fact_source_pages';
export const MAX_FACT_SOURCE_PAGES = 2;
/** Source pages go in after this many organic rows. */
export const FACT_SOURCE_PAGE_RANK = 3;
const MONTHS = 'january|february|march|april|may|june|july|august|september|october|november|december';
const TEMPORAL_CUE = new RegExp(`\\b(when|before|after|since|until|till|during|ago|earlier|later|earliest|latest|first|last|previous|next|dates?|day|week|month|year|order|sequence|${MONTHS})\\b`
+ `|\\bhow (long|many (days|weeks|months|years))\\b|\\bwhat time\\b|\\b\\d{4}-\\d{2}-\\d{2}\\b`, 'i');
/** Whether `query` carries a deterministic temporal cue (the preregistered word, phrase, ISO date and month-name list). */
export function hasTemporalCue(query: string): boolean {
return TEMPORAL_CUE.test(query);
}
const HISTORY_CUE = /\b(before|earlier|earliest|previous(ly)?|prior|former(ly)?|used to|originally|first|history|historically|ever|over time|in order|chronolog\w*|sequence|ago|back then|at the time|no longer|any ?more|in the past)\b/i;
const today = () => new Date().toISOString().slice(0, 10);
/**
* GBRA-574 B1: whether `query` asks about the past, by a plain-English history word or a time it names (the shared
* temporal grammar, temporal-grammar.ts) that ended before `asOf` (today by default).
*/
export function hasHistoryCue(query: string, asOf = today()): boolean {
return HISTORY_CUE.test(query) || findTimeMentions(query, asOf, 'past').some(m => m.end < asOf);
}
/** GBRA-574 B3: the one date `query` names (the last day of it, YYYY-MM-DD, by the shared temporal grammar), or null for none or several. */
export function questionDate(query: string, asOf = today()): string | null {
const ends = [...new Set(findTimeMentions(query, asOf, 'past').filter(m => m.kind === 'absolute').map(m => m.end))];
return ends.length === 1 ? ends[0]! : null;
}
export interface FactsArmScope {
sourceId?: string; sourceIds?: string[]; remote: boolean;
/** #5575 read floor and activation control, applied in the candidate SQL like every retrieval arm. */
minTrust?: TrustTier; suppressFlagged?: boolean;
}
type FactCandidate = PoolCandidate;
async function poolScope(engine: BrainEngine, scope: FactsArmScope): Promise<FactPoolScope> {
return { ...scope, worldOnly: worldOnlyFacts(scope.remote), excludePrivate: await resolveExcludePrivatePages(engine, scope.remote) };
}
const day = (v: Date | string | null) => (v ? new Date(v).toISOString().slice(0, 10) : null);
/** The active facts that match `query`, newest valid_from first (at most MAX_FACT_ROWS). */
export async function matchQueryFacts(engine: BrainEngine, query: string, scope: FactsArmScope, queryEmbedding?: Float32Array | null): Promise<FactCandidate[]> {
const { candidates } = await collectFactCandidates(engine, query, await poolScope(engine, scope), queryEmbedding, { depth: { keyword: 50, cosine: 10, entity: MAX_FACT_ROWS } });
const terms = queryTerms(query);
const matched = (c: FactCandidate) => { const haystack = `${c.fact} ${c.entity_slug ?? ''}`.toLowerCase(); return terms.filter(t => haystack.includes(t)).length; };
return candidates
.filter(c => c.entity || (c.similarity ?? -1) >= FACT_COSINE_MIN || (terms.length > 0 && matched(c) >= Math.max(Math.min(2, terms.length), Math.ceil(terms.length * TERM_SHARE_MIN))))
.sort((a, b) => new Date(b.valid_from).getTime() - new Date(a.valid_from).getTime() || Number(b.id) - Number(a.id))
.slice(0, MAX_FACT_ROWS);
}
/**
* When each fact was said (evidence-date.ts `factObservationDates`, under the caller's page read policy), or null
* when the read failed: its rows then carry `observed_unavailable` and the response is marked degraded.
*/
async function observedDates(engine: BrainEngine, facts: FactCandidate[], readScope: PageReadScope | undefined): Promise<{ dates: Map<number, string> | null; timeZone: string | null }> {
const timeZone = (await engine.getConfig('brain.timezone').catch(() => null))?.trim() || null;
try {
return { dates: await factObservationDates(engine, facts, timeZone, readScope), timeZone };
} catch {
return { dates: null, timeZone };
}
}
function factRow(f: FactCandidate, score: number, pageSlug: string | undefined, fromQuotedPage: boolean, observed: Map<number, string> | null): SearchResult {
const from = day(f.valid_from);
const until = day(f.valid_until);
const args: Record<string, string> = f.entity_slug ? { entity: f.entity_slug } : { grep: f.fact.slice(0, 60) };
if (f.source_id !== 'default') args.source_id = f.source_id;
return {
result_type: 'fact', fact_id: String(f.id), ...(pageSlug ? { page_slug: pageSlug } : {}), follow_up: { op: 'recall', args },
slug: `facts/${f.id}`, page_id: 0, title: f.entity_slug ? `Saved fact about ${f.entity_slug}` : 'Saved fact', type: 'note',
chunk_text: `Saved fact (${f.kind}; valid from ${from ?? 'unknown'}${until ? ` to ${until}` : ''}; provenance: ${f.source}): ${f.fact}`,
chunk_source: 'compiled_truth', chunk_id: -Number(f.id), chunk_index: 0, score, stale: false, source_id: f.source_id,
fact_row: { id: Number(f.id), valid_from: new Date(f.valid_from).toISOString(), valid_until: f.valid_until ? new Date(f.valid_until).toISOString() : null, source: f.source,
...(fromQuotedPage ? { from_quoted_page: true as const } : {}),
...(observed === null ? { observed_unavailable: true as const } : observed.has(Number(f.id)) ? { observed: observed.get(Number(f.id))! } : {}) },
} as SearchResult;
}
/**
* Stamp `superseded_claim` on page rows whose page is the source of an older
* fact for the same entity and typed claim slot as a newer matched fact.
* Untyped claims are never compared.
*/
async function stampSupersededClaims(engine: BrainEngine, results: SearchResult[], facts: FactCandidate[]): Promise<void> {
const typed = facts.filter(f => f.entity_slug && f.claim_metric);
const pages = results.filter(r => !r.fact_row && r.slug);
if (!typed.length || !pages.length) return;
const rows = await engine.executeRaw<{ id: number; source_markdown_slug: string; source_id: string; entity_slug: string; claim_metric: string; claim_period: string | null; valid_from: Date | string }>(
`SELECT f.id, f.source_markdown_slug, f.source_id, f.entity_slug, f.claim_metric, f.claim_period, f.valid_from FROM facts f
WHERE f.source_markdown_slug = ANY($1::text[]) AND f.entity_slug = ANY($2::text[]) AND f.claim_metric IS NOT NULL`,
[[...new Set(pages.map(r => r.slug))], [...new Set(typed.map(f => f.entity_slug!))]]);
for (const r of pages) {
for (const old of rows.filter(o => o.source_markdown_slug === r.slug && o.source_id === (r.source_id ?? o.source_id))) {
const newer = typed.find(f => f.entity_slug === old.entity_slug && f.claim_metric === old.claim_metric
&& (!f.claim_period || !old.claim_period || f.claim_period === old.claim_period)
&& Number(f.id) !== Number(old.id) && new Date(f.valid_from).getTime() > new Date(old.valid_from).getTime());
if (newer) { r.superseded_claim = { fact_id: Number(newer.id), valid_from: new Date(newer.valid_from).toISOString() }; break; }
}
}
}
/** `source\0slug` keys of the facts' entity pages (page slug = fact entity_slug, same source) the caller may read. */
async function readableEntityPages(engine: BrainEngine, facts: FactCandidate[], scope: PageReadScope | undefined): Promise<Set<string>> {
const slugs = [...new Set(facts.flatMap(f => f.entity_slug ? [f.entity_slug] : []))];
if (!slugs.length) return new Set();
const params: unknown[] = [slugs];
const filter = pageReadFilter('p', scope, params, true);
const rows = await engine.executeRaw<{ slug: string; source_id: string }>(`SELECT p.slug, p.source_id FROM pages p WHERE p.slug = ANY($1::text[]) AND ${filter}`, params);
return new Set(rows.map(r => `${r.source_id}\u0000${r.slug}`));
}
/**
* What a caller sees of a fact row: the fact, its identity and how to follow
* it, never page fields (slug, id, type, chunk_id) that would invite get_page
* or fetch on a page that may not exist.
*/
export function factRowOutput<T extends Partial<SearchResult>>(row: T): T {
if (row.result_type !== 'fact') return row;
const { slug: _slug, id: _id, type: _type, chunk_id: _chunk, page_id: _page, chunk_index: _index, chunk_source: _source, fact_row: _fact, ...rest } = row as T & { id?: string };
return rest as T;
}
export interface FactsArmOpts extends FactsArmScope {
/** The caller's page read policy: a fact's entity page is named (`page_slug`) only when the caller may read it. */
readScope?: PageReadScope;
tokenBudget?: number;
queryEmbedding?: Float32Array | null;
/** The caller's row count (explicit limit or the mode's default), read only when a fact matches. */
rowCap?: () => Promise<number>;
}
/**
* The facts arm: matched facts appended as rows in spare capacity only (free
* slots under the caller's row count, and what the pages leave of the token
* budget), so no page row is ever displaced; superseded page claims stamped.
* No match, no spare capacity or any error: the results unchanged.
*/
export async function applyFactsArm(engine: BrainEngine, query: string, results: SearchResult[], opts: FactsArmOpts): Promise<SearchResult[]> {
try {
const facts = await matchQueryFacts(engine, query, opts, opts.queryEmbedding);
if (!facts.length) return results;
const free = ((await opts.rowCap?.().catch(() => 0)) ?? 0) - results.length;
if (free <= 0) return results;
const pages = results.map(r => ({ ...r }));
const floor = pages.reduce((m, r) => (Number.isFinite(r.score) && r.score < m ? r.score : m), pages[0]?.score ?? 1);
const shown = facts.slice(0, free);
const pageSlugs = await readableEntityPages(engine, shown, opts.readScope).catch(() => new Set<string>());
const fromQuoted = await factsFromQuotedPages(engine, shown.map(f => Number(f.id)));
const { dates } = await observedDates(engine, shown, opts.readScope);
let rows = shown.map((f, i) => factRow(f, floor - (i + 1) * 1e-6, f.entity_slug && pageSlugs.has(`${f.source_id}\u0000${f.entity_slug}`) ? f.entity_slug : undefined, fromQuoted.has(Number(f.id)), dates));
if (opts.tokenBudget) {
let left = opts.tokenBudget - enforceTokenBudget(pages, opts.tokenBudget).meta.used;
rows = rows.filter(r => { const cost = resultTokens(r); if (cost > left) return false; left -= cost; return true; });
}
if (!rows.length) return results;
const merged = [...pages, ...rows];
await stampSupersededClaims(engine, merged, facts).catch(() => undefined);
return merged;
} catch {
return results;
}
}
interface ReservePolicy {
share: number;
maxRows: number;
/** Share of the caller's row count the facts may take (they replace the lowest page rows); null: they add rows. */
rowShare: number | null;
/** Where the facts go: after the pages (temporal reserve) or ahead of them (facts block). */
position: 'after' | 'before';
/** GBRA-574 B1, B3, G1 and B5: ended facts on a history cue, the asked date in each header, contested labels and later retractions. */
dated: boolean;
}
const TEMPORAL_RESERVE: ReservePolicy = { share: TEMPORAL_RESERVE_SHARE, maxRows: MAX_RESERVE_ROWS, rowShare: TEMPORAL_RESERVE_ROW_SHARE, position: 'after', dated: false };
const FACTS_BLOCK: ReservePolicy = { share: QUERY_FACTS_BLOCK_SHARE, maxRows: MAX_FACTS_BLOCK_ROWS, rowShare: null, position: 'before', dated: true };
/**
* Temporal fact reserve: for a query with a temporal cue and a token budget,
* the facts that best match the question (the shared scorer in
* fact-relevance.ts: cosine + term share, +0.1 when the fact carries a real
* date, admitted by the reserve rule) take up to TEMPORAL_RESERVE_SHARE of the budget and
* TEMPORAL_RESERVE_ROW_SHARE of the row count (1 to MAX_RESERVE_ROWS rows), rendered with their date header and ordered oldest
* first after the pages. The row count never grows (a fact takes a free row,
* else the lowest page row) and pages fill the rest of the budget. No match or
* any error: the results unchanged.
*/
export function applyTemporalFactReserve(engine: BrainEngine, query: string, results: SearchResult[], opts: FactsArmOpts & { budget: number }): Promise<SearchResult[]> {
return applyFactReserve(engine, query, results, opts, TEMPORAL_RESERVE);
}
/**
* Facts block (GBRA-205): the same question-ranked, dated facts as the
* temporal reserve, for every query whose caller passed a token budget, up to
* QUERY_FACTS_BLOCK_SHARE of the budget and MAX_FACTS_BLOCK_ROWS rows and
* never more rows than the caller's row count (#8411), oldest first ahead of
* the pages. Copies of one claim take one row, dated as first stated with
* "(stated N times, last D)" after the fact (GBRA-574 A2), and each row's date
* header carries when the fact was said (A1). On a history cue (`hasHistoryCue`)
* the pool also takes the named entity's ended facts with their windows (B1;
* never a withdrawn or forgotten one); when the question names one date each
* header says whether the fact was told after it (B3); and a fact in a pending
* supersede proposal ends "(contested by #<id>)" when the caller can read the
* other fact, as recall labels it (G1). A later fact of the same entity that retracts a shown fact or calls it off (a
* plain-English cue not negated just before it, whose non-name terms are all in the fact or share two with it, or
* carrying the fact's slot; fact-relevance.ts `laterRetractions`) follows it with
* its own date, inside the same share and row count (B5). Block rows take the top page's
* score: they are placed, not ranked against the pages, and never outscore them. The facts add rows
* (every page row stays) and pages fill the rest of the budget. No match or
* any error: the results unchanged.
*/
export function applyFactsBlock(engine: BrainEngine, query: string, results: SearchResult[], opts: FactsArmOpts & { budget: number }): Promise<SearchResult[]> {
return applyFactReserve(engine, query, results, opts, FACTS_BLOCK);
}
async function applyFactReserve(engine: BrainEngine, query: string, results: SearchResult[], opts: FactsArmOpts & { budget: number }, policy: ReservePolicy): Promise<SearchResult[]> {
try {
const scope = await poolScope(engine, opts);
const readScope: PageReadScope = opts.readScope ?? { sourceId: opts.sourceId, sourceIds: opts.sourceIds, excludePrivate: scope.excludePrivate };
// GBRA-574 F: a history question about one slot dimension of one named entity takes every value it has had, first in line (slot-history.ts).
let historyUnavailable = false;
const history = policy.dated ? await readSlotHistory(engine, query, scope, readScope).catch(() => { historyUnavailable = true; return null; }) : null;
const pinned = new Set((history?.rows ?? []).map(c => Number(c.id)));
const { candidates, stems } = await collectFactCandidates(engine, query, scope, opts.queryEmbedding,
{ depth: { keyword: 50, cosine: 50, entity: policy.maxRows }, cosineForAll: true, history: policy.dated && hasHistoryCue(query) });
const scored = [...(history?.rows ?? []), ...scoreFactCandidates(query, candidates, queryTerms(query), stems)
.filter(s => admitted(s, 'reserve') && !pinned.has(Number(s.candidate.id))).map(s => s.candidate)];
if (!scored.length) return results;
const callerRows = (await opts.rowCap?.().catch(() => 0)) ?? 0;
const rowCap = Math.max(results.length, callerRows);
const maxRows = policy.rowShare === null ? Math.min(policy.maxRows, callerRows || policy.maxRows) : Math.min(policy.maxRows, Math.max(1, Math.floor(rowCap * policy.rowShare)));
// GBRA-574 A2: copies of one claim (exact fingerprint, capture-dedup.ts) take one row, shown as first stated; a differing value never merges.
const byId = new Map(scored.map(c => [Number(c.id), c]));
const collapsed = await collapseFactReads(engine, scored.map(c => ({ ...c, id: Number(c.id), created_at: c.created_at ?? c.valid_from, visibility: c.visibility ?? '', attributed_to: c.attributed_to ?? null })));
const members = collapsed.map(r => (r.collapsed_ids ?? [r.id]).map(id => byId.get(id)!));
// GBRA-574 B5: later facts that retract or call off a pooled fact, read under the same policy.
const answers = policy.dated ? await laterRetractions(engine, scope, members.flat()).catch(() => new Map<number, FactCandidate[]>()) : new Map<number, FactCandidate[]>();
const retracting = [...new Map([...answers.values()].flat().filter(r => !byId.has(r.id)).map(r => [r.id, r])).values()];
const { dates } = await observedDates(engine, [...members.flat(), ...retracting], opts.readScope);
const said = (c: FactCandidate) => dates?.get(Number(c.id)) ?? day(c.created_at ?? c.valid_from) ?? '';
const groups = members.map(g => g.sort((a, b) => said(a).localeCompare(said(b)) || Number(a.id) - Number(b.id)));
const shown = groups.map(g => g[0]!);
// GBRA-574 B2/G4 and F: a slot value's window ends at read time, from the rows the caller may read under every key of its entity (slot-history.ts).
const ends = await slotWindows(engine, scope, readScope, shown, history?.keys ?? null)
.catch(() => { historyUnavailable ||= history !== null; return new Map<number, Date>(); });
const pageSlugs = await readableEntityPages(engine, shown, opts.readScope).catch(() => new Set<string>());
const fromQuoted = await factsFromQuotedPages(engine, [...shown, ...retracting].map(c => Number(c.id)));
const asked = policy.dated ? questionDate(query) : null;
const lookup: ContestedLookup = {};
const contested = policy.dated
? new Map((await withDecideContested<{ id: number; contested?: Contested }>(engine, shown.map(c => ({ id: Number(c.id) })),
{ remote: opts.remote, excludePrivate: scope.excludePrivate, eligibility: { floor: opts.minTrust, suppressFlagged: opts.suppressFlagged } }, lookup))
.flatMap(r => (r.contested ? [[r.id, r.contested.fact_id] as const] : [])))
: new Map<number, string>();
let left = Math.floor(opts.budget * policy.share);
const render = (group: FactCandidate[]) => {
const c = group[0]!;
const restated = group.length > 1 ? ` (stated ${group.length} times, last ${said(group[group.length - 1]!)})` : '';
const row = factRow(c, 0, c.entity_slug && pageSlugs.has(`${c.source_id}\u0000${c.entity_slug}`) ? c.entity_slug : undefined, fromQuoted.has(Number(c.id)), dates);
const window = c.valid_until ? c : { ...c, valid_until: ends.get(Number(group[group.length - 1]!.id)) ?? null };
const label = contested.has(Number(c.id)) ? ` (contested by #${contested.get(Number(c.id))})` : '';
row.chunk_text = `${factDateHeader(window, undefined, dates?.get(Number(c.id)), asked)}\n${c.fact}${restated}${label}`;
if (lookup.degraded) row.fact_row = { ...row.fact_row!, contested_unavailable: true };
if (historyUnavailable) row.fact_row = { ...row.fact_row!, history_unavailable: true };
return row;
};
type Shown = { c: FactCandidate; row: SearchResult; after: Array<{ c: FactCandidate; row: SearchResult }> };
const chosen: Shown[] = [];
const groupOf = new Map(groups.flatMap(g => g.map(m => [Number(m.id), g] as const)));
const attached = new Set<number>();
let count = 0;
for (const group of groups) {
if (count >= maxRows) break;
const c = group[0]!;
if (attached.has(Number(c.id))) continue;
const row = render(group);
const cost = resultTokens(row);
if (cost > left) continue;
left -= cost;
const entry: Shown = { c, row, after: [] };
chosen.push(entry);
count++;
// GBRA-574 B5: each later retraction goes right after the fact it answers; one already shown moves there.
for (const r of answers.get(Number(c.id)) ?? []) {
const g = groupOf.get(r.id) ?? [r];
const head = Number(g[0]!.id);
if (head === Number(c.id) || attached.has(head)) continue;
const at = chosen.findIndex(x => Number(x.c.id) === head);
if (at >= 0) {
const [moved] = chosen.splice(at, 1);
entry.after.push({ c: moved!.c, row: moved!.row }, ...moved!.after);
attached.add(head);
continue;
}
if (count >= maxRows) break;
const answer = render(g);
const answerCost = resultTokens(answer);
if (answerCost > left) continue;
left -= answerCost;
entry.after.push({ c: g[0]!, row: answer });
attached.add(head);
count++;
}
}
if (!chosen.length) return results;
chosen.sort((a, b) => new Date(a.c.valid_from).getTime() - new Date(b.c.valid_from).getTime() || Number(a.c.id) - Number(b.c.id));
const pagesFloor = results.reduce((m, r) => (Number.isFinite(r.score) && r.score < m ? r.score : m), results[0]?.score ?? 1);
const pagesTop = results.reduce((m, r) => (Number.isFinite(r.score) && r.score > m ? r.score : m), results[0]?.score ?? 1);
const placed = chosen.flatMap(({ c, row, after }) => [{ c, row }, ...after]);
const rows = policy.position === 'after'
? placed.map(({ row }, i) => ({ ...row, score: pagesFloor - (i + 1) * 1e-6 }))
: placed.map(({ row }) => ({ ...row, score: pagesTop }));
let pages = (policy.rowShare === null ? results : results.slice(0, Math.max(0, Math.min(results.length, rowCap - rows.length)))).map(r => ({ ...r }));
if (opts.tokenBudget) pages = enforceTokenBudget(pages, Math.max(1, opts.tokenBudget - rows.reduce((n, r) => n + resultTokens(r), 0))).results;
const merged = policy.position === 'after' ? [...pages, ...rows] : [...rows, ...pages];
await stampSupersededClaims(engine, merged, placed.map(x => x.c)).catch(() => undefined);
return merged;
} catch {
return results;
}
}
/**
* Fact source pages (GBRA-205): the conversations the question's best-matching
* facts were extracted from (`facts.source_markdown_slug`, never the fact's
* own entity page), up to MAX_FACT_SOURCE_PAGES not already in the results,
* go in after the top FACT_SOURCE_PAGE_RANK rows, so evidence delivery can
* hand over the whole session. Each page is read through `getChunkWindows`
* under the caller's read scope, so an unreadable page is absent. The row
* count never grows (the lowest rows give way). No match or any error: the
* results unchanged.
*/
export async function applyFactSourcePages(engine: BrainEngine, query: string, results: SearchResult[], opts: FactsArmOpts): Promise<SearchResult[]> {
try {
const { candidates, stems } = await collectFactCandidates(engine, query, await poolScope(engine, opts), opts.queryEmbedding,
{ depth: { keyword: 50, cosine: 50, entity: MAX_RESERVE_ROWS }, cosineForAll: true });
const ranked = scoreFactCandidates(query, candidates, queryTerms(query), stems).filter(s => admitted(s, 'reserve')).map(s => Number(s.candidate.id));
if (!ranked.length) return results;
const sources = await engine.executeRaw<{ id: number; page_id: number; slug: string; title: string | null; type: string | null }>(
`SELECT f.id, p.id AS page_id, p.slug, p.title, p.type FROM facts f
JOIN pages p ON p.source_id = f.source_id AND p.slug = f.source_markdown_slug AND p.deleted_at IS NULL
WHERE f.id = ANY($1::bigint[]) AND f.source_markdown_slug IS DISTINCT FROM f.entity_slug`, [ranked]);
const rank = new Map(ranked.map((id, i) => [id, i]));
const present = new Set(results.map(r => r.page_id));
const wanted: typeof sources = [];
for (const s of [...sources].sort((a, b) => rank.get(Number(a.id))! - rank.get(Number(b.id))!)) {
if (wanted.length >= MAX_FACT_SOURCE_PAGES) break;
if (present.has(Number(s.page_id)) || !conversationSignal({ type: s.type, slug: s.slug })) continue;
present.add(Number(s.page_id));
wanted.push(s);
}
if (!wanted.length) return results;
const windows = await engine.getChunkWindows(wanted.map((w, i) => ({ page_id: Number(w.page_id), from_index: 0, to_index: 0, priority: i })),
{ sourceId: opts.readScope?.sourceId, sourceIds: opts.readScope?.sourceIds, excludePrivate: opts.readScope?.excludePrivate, requireSafeChunks: opts.readScope?.requireSafeChunks,
minTrust: opts.readScope?.minTrust, suppressFlagged: opts.readScope?.suppressFlagged, chunkSources: ['compiled_truth'], maxRows: wanted.length });
const byId = new Map(windows.map(w => [w.page_id, w]));
const at = Math.min(FACT_SOURCE_PAGE_RANK, results.length);
const above = results[at - 1]?.score ?? 1;
const added: SearchResult[] = [];
for (const w of wanted) {
const window = byId.get(Number(w.page_id));
const chunk = window?.chunks[0];
if (!window || !chunk) continue;
added.push({
page_id: Number(w.page_id), slug: window.slug, title: w.title ?? window.slug, type: window.type as SearchResult['type'], source_id: window.source_id,
chunk_text: chunk.chunk_text, chunk_index: chunk.chunk_index, chunk_id: chunk.id, chunk_source: chunk.chunk_source as SearchResult['chunk_source'],
score: above - (added.length + 1) * 1e-9, stale: false,
} as SearchResult);
}
if (!added.length) return results;
const rowCap = Math.max(results.length, (await opts.rowCap?.().catch(() => 0)) ?? 0);
return [...results.slice(0, at), ...added, ...results.slice(at)].slice(0, rowCap);
} catch {
return results;
}
}
/** `search.temporal_fact_reserve` is on ('true' | 'on' | '1' | 'yes'); off by default and on any read error. */
export async function temporalFactReserveEnabled(engine: { getConfig(key: string): Promise<string | null> }): Promise<boolean> {
try {
return configFlagOn(await engine.getConfig(TEMPORAL_FACT_RESERVE_KEY));
} catch {
return false;
}
}
/** `search.query_facts_block` is on by default; 'false' | 'off' | '0' | 'no' turns it off, and so does any read error. */
export async function queryFactsBlockEnabled(engine: { getConfig(key: string): Promise<string | null> }): Promise<boolean> {
try {
const raw = (await engine.getConfig(QUERY_FACTS_BLOCK_KEY))?.trim().toLowerCase();
return !(raw === 'false' || raw === 'off' || raw === '0' || raw === 'no');
} catch {
return false;
}
}
/** `search.fact_source_pages` is on ('true' | 'on' | '1' | 'yes'); off by default and on any read error. */
export async function factSourcePagesEnabled(engine: { getConfig(key: string): Promise<string | null> }): Promise<boolean> {
try {
return configFlagOn(await engine.getConfig(FACT_SOURCE_PAGES_KEY));
} catch {
return false;
}
}
/**
* `search.query_facts_arm`: on by default (gates 1b and 2 passed,
* docs/eval/decisions/query-facts-arm/); 'false' | 'off' | '0' | 'no' turns it
* off. A config read error leaves it off.
*/
export async function queryFactsArmEnabled(engine: { getConfig(key: string): Promise<string | null> }): Promise<boolean> {
try {
const raw = (await engine.getConfig(QUERY_FACTS_ARM_KEY))?.trim().toLowerCase();
return !(raw === 'false' || raw === 'off' || raw === '0' || raw === 'no');
} catch {
return false;
}
}