Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Write-time fact subject inference for the facts backstop (#5836).
*
* The extractor sometimes returns a fact with no entity, or one that names
* no live page. `inferMissingSubjects` gives such a fact the subject that
* `inferFactSubject` proves from identity evidence (the page being written,
* or one exact mention), and marks it `entity_inferred` so the writers
* annotate its context and never supersede or drop a similar fact for it.
*
* Inference is applied only where the fact will be fenced: the unmanaged
* DB-only branch (no local_path, or write-through off) would leave a
* row_num-NULL row on a live page and jam the extract_facts legacy guard,
* so those facts stay unattributed. A link is also dropped whenever the
* writer would refuse it: caller slug fences, the managed batch's grant and
* page visibility, a withdrawn claim, or a malformed target fence (which
* would fail the whole write, read as that writer reads it: #9279). Remote callers infer only from the page
* actually being written and never from pages they cannot read.
*/
import type { BrainEngine } from '../engine.ts';
import type { FactsBackstopCtx } from './backstop.ts';
import type { ExtractedFact } from './extract.ts';
import type { ManagedFactsSession } from '../persistence/facts-maintenance.ts';
import { inferFactSubject, isEntityInferenceEnabled, type InferredVia } from './subject-infer.ts';
import { isNullLikeEntity } from './write-single.ts';
/** The context note an inferred link carries, in the DB row and the fence cell alike. */
export function inferenceNote(via: InferredVia): string {
return `entity inferred from ${via}`;
}
export async function inferMissingSubjects(ctx: FactsBackstopCtx, facts: ExtractedFact[], visibility: 'private' | 'world',
pageSlug: string | undefined, managed: ManagedFactsSession | null): Promise<ExtractedFact[]> {
const engine = ctx.engine;
if (!facts.length || !(await isEntityInferenceEnabled(engine))) return facts;
if (!managed && await writesDatabaseOnly(engine, ctx.sourceId)) return facts;
const { excludesPrivateWrites } = await import('../persistence/page-visibility.ts');
const remote = managed ? managed.authority.remote : (ctx.operationContext?.remote ?? ctx.remote) !== false;
const excludePrivate = managed?.authority.excludePrivate === true || await excludesPrivateWrites(engine, remote);
const fromPage = remote ? pageSlug : ctx.sourceSlug ?? pageSlug;
const out: ExtractedFact[] = [];
const fences = new Map<string, Promise<boolean>>();
for (const f of facts) {
// An extractor-named entity is kept even when it has no page: that name
// competes with any page the text mentions, so inference never overrides it.
if (!isNullLikeEntity(f.entity_slug)) { out.push(f); continue; }
const inferred = await inferFactSubject(engine, ctx.sourceId, { fact: f.fact, pageSlug: fromPage, mode: 'write', excludePrivate });
if (inferred.slug !== null && await linkAllowed(ctx, inferred.slug, f.fact, visibility, remote, managed, fences)) {
out.push({ ...f, entity_slug: inferred.slug, entity_inferred: inferred.via });
} else out.push(f);
}
return out;
}
async function writesDatabaseOnly(engine: BrainEngine, sourceId: string): Promise<boolean> {
const { isWriteThroughDisabled } = await import('../write-through.ts');
const { lookupSourceLocalPath } = await import('./fence-write.ts');
return await isWriteThroughDisabled(engine) || await lookupSourceLocalPath(engine, sourceId) === null;
}
async function linkAllowed(ctx: FactsBackstopCtx, slug: string, fact: string, visibility: string, remote: boolean,
managed: ManagedFactsSession | null, fences: Map<string, Promise<boolean>>): Promise<boolean> {
const engine = ctx.engine;
const { isFactWithdrawn } = await import('./withdrawal.ts');
if (await isFactWithdrawn(engine, ctx.sourceId, visibility, fact, slug)) return false;
try {
const op = ctx.operationContext;
if (remote && op) {
const { enforceClientSlugFence, enforceSubagentSlugFence, validatePageSlug } = await import('../ops/context.ts');
validatePageSlug(slug);
enforceClientSlugFence(op, slug, 'extract_facts');
enforceSubagentSlugFence(op, slug, 'extract_facts');
}
if (managed) {
const { authorizeWrite } = await import('../persistence/authority.ts');
const { authorizePageVisibility } = await import('../persistence/page-visibility.ts');
await authorizeWrite(engine, managed.authority, 'extract_facts', slug);
await authorizePageVisibility(engine, managed.authority, slug);
}
} catch (error) {
const { OperationError } = await import('../ops/contract.ts');
if (error instanceof OperationError) return false;
throw error;
}
if (!fences.has(slug)) fences.set(slug, targetFenceClean(engine, ctx.sourceId, slug, managed !== null));
return fences.get(slug)!;
}
/**
* #9279: whether the target's facts fence parses cleanly, read as its writer reads it. The managed writer reads a page
* stored in segments back whole up to the single-string ceiling; the unmanaged fence writer records a segmented page's
* facts database-only, and an over-ceiling page takes no fence row, so neither is a link target there.
*/
async function targetFenceClean(engine: BrainEngine, sourceId: string, slug: string, managed: boolean): Promise<boolean> {
const snapshot = await engine.readPageSnapshot(slug, { sourceId });
if (!snapshot) return false;
const { isSegmentedPage } = await import('../page-body/page-shape.ts');
const { materializedSnapshot, segmentedOverCeiling } = await import('../persistence/segmented-apply.ts');
if (isSegmentedPage(snapshot.page) && (!managed || segmentedOverCeiling(snapshot.page))) return false;
let body: string;
try {
body = (await materializedSnapshot(engine, snapshot))!.page.compiled_truth;
} catch (error) {
const { OperationError } = await import('../ops/contract.ts');
if (error instanceof OperationError) return false;
throw error;
}
const { parseFactsFence } = await import('../facts-fence.ts');
return parseFactsFence(body).warnings.length === 0;
}