Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
44.2 KB
Raw Blame
/**
 * MEMORY_VERBS v1 — `entity(name)` card builder (zero LLM, p99 < 100ms).
 *
 * Resolves a free-text name to ONE brain page via the Retrieval Reflex's
 * precision-biased arms (alias-first, then exact-title / exact-slug /
 * slug-suffix), then assembles a compact self-describing card from parallel
 * depth-1 indexed reads. Deliberately NOT the recursive-CTE traversal
 * (traversePaths) — the card is a latency contract, not a graph walk.
 *
 * Resolution precedence (frozen): alias > exact slug > exact title >
 * slug-suffix. Exact-title collisions prefer entity-shaped pages over
 * transcript/note containers; otherwise ties break on GREATEST(updated_at,
 * last_retrieved_at) — "last_touched" is the card's OUTPUT name, not a
 * column. Multi-hit → best match wins, runners-up land in `suggestions`.
 * Miss → `found: false` + keyword near-misses with create_safety hints. NEVER
 * throws for data reasons; each arm is guarded so a pre-page_aliases brain
 * still resolves via arm 2 (same posture as the shipped reflex).
 *
 * Privacy: `summary` runs through safeSynopsis (the get_page fence boundary);
 * facts respect visibility for remote callers (world-only).
 */

import { annotateTemporalRow, LIVENESS_EXEMPT_LINK_TYPES, temporalLinkJoinSql, TEMPORAL_LINK_SELECT_SQL, type TemporalAnnotation } from '../link-validity.ts';
import type { BrainEngine, FactRow } from '../engine.ts';
import type { TrustTier } from '../trust/tier.ts';
import type { ReadEligibility } from '../eligibility/policy.ts';
import { trustFields } from '../eligibility/labels.ts';
import { isQuarantined } from '../quarantine.ts';
import { loadPageTrust } from '../eligibility/stamp.ts';
import { storedEdge, worldLinkContexts } from '../eligibility/fence-overlay.ts';
import { projectionEligibleSql } from '../eligibility/sql.ts';
import { loadRelationshipNotes, relationshipNoteKey } from '../link-relationship-notes.ts';
import { normalizeAlias } from '../search/alias-normalize.ts';
import { isIdentityEntity, slugify } from '../entities/resolve.ts';
import { nameVariantsEnabled, readPossibleDuplicates, resolveNameVariant, type PossibleDuplicate } from './entity-variants.ts';
import { readTextMentions, type TextMentions } from './entity-text-mentions.ts';
import type { NameMatchKind } from '../entities/name-variants.ts';
import { exactMatchPreference } from '../entities/exact-match-preference.ts';
import { safeSynopsis } from '../context/retrieval-reflex.ts';
import { stampEvidence, markKeywordHits } from '../search/evidence.ts';
import type { Link, SearchResult } from '../types.ts';
import type { NewerMentions } from '../mentions/newer-mentions.ts';
import { linkableTypesFor, loadLinkableTypes, loadSourcePack, readMentionPolicy, type MentionPolicy, type PackTypes } from '../mentions/policy.ts';
import { readMentionCoverage, type MentionCoverage } from '../mentions/coverage.ts';
import { encodeCursor, readReferrerGroups, PAGE_DEFAULT_LIMIT, type ReferenceRow } from '../mentions/referrers.ts';
import { readRowReferences, referencesUnavailableNotice, type RecordGroupView, type ReferencesUnavailable, type RowReferences } from './entity-references.ts';
import type { Notice } from '../agent-output.ts';
import { readCardIdentity, type CardIdentity } from './entity-card-identity.ts';
import { factEntitySlugs } from '../mentions/siblings.ts';
import { boundedBodyPrefixSql, overlaidBoundedRows } from '../page-window/bounded-lead.ts';

const EDGE_CAP = 10;
const OPEN_THREADS_CAP = 3;
const OPEN_THREAD_TIMELINE_WINDOW_DAYS = 90;
const SUGGESTION_CAP = 3;
/** Keyword hits read for near-miss suggestions before keeping entity pages only. */
const NEAR_MISS_POOL = 20;
const FACT_FETCH_CAP = 100;
export const RECENT_FACTS_CAP = 5;

export interface EntityCardEdge {
  type: string;
  direction: 'out' | 'in';
  slug: string;
  context: string | null;
  /** Relationship status today: live, ended, ended_unknown_date, event, reference, … */
  status?: string;
  /** Latest stint bounds (YYYY-MM-DD) when the relationship has dated evidence. */
  since?: string | null;
  until?: string | null;
}

export interface EntityOpenThread {
  kind: 'commitment' | 'recent_event';
  text: string;
  date: string | null;
  /**
   * v0.47 open-loop engine — ADDITIVE OPTIONAL fields (legal under the
   * MEMORY_VERBS v1 freeze; absent on threads not backed by an open_loops
   * row). direction is from the account owner's perspective.
   */
  direction?: 'owed_by_me' | 'owed_to_me' | 'their_turn' | 'my_turn';
  due?: string | null;
  counterparty?: string | null;
  status?: string;
  loop_id?: number;
  /** #5575 A6 (additive): the trust tier and short origin of the fact or timeline row behind the thread. */
  trust_tier?: TrustTier;
  origin?: string;
}

export interface EntityCard {
  /** #6723: `source_id` is the source the page lives in; (source_id, slug) is the entity's identity. */
  entity: { slug: string; title: string; type: string | null; source_id: string };
  /** page_aliases reverse lookup (normalized forms). Empty on pre-migration brains. */
  aka: string[];
  /** Privacy-safe synopsis — same fence boundary as get_page. */
  summary: string;
  last_touched: {
    updated_at: string | null;
    last_retrieved_at: string | null;
    last_timeline_date: string | null;
  };
  /** Best-effort in v1: active commitment-kind facts + recent timeline entries. */
  open_threads: EntityOpenThread[];
  /** Top typed edges, mentions excluded, out-edges first. */
  edges: EntityCardEdge[];
  backlink_count: number;
  /** Exact active-fact count (indexed COUNT, not payload length); visibility-filtered for remote. */
  active_fact_count: number;
  /** The newest active saved facts about this entity (also those saved under an identity sibling or its bare name, with that `entity_slug`). */
  recent_facts?: Array<{ id: string; fact: string; kind: string; valid_from: string | null; entity_slug?: string }>;
  /**
   * Current and ended state relationships of this entity, rendered for agents
   * ("now: works_at widget-co (since 2025-03-01); ended: works_at acme-example
   * (2025-03-01)"), plus a stale-summary warning when the summary still names
   * a relationship that ended. Absent when there is nothing to say.
   */
  relationship_note?: string;
  /** F3: this page's own frontmatter `status` (a string up to 40 characters), only when set. `context_pack` cards only. */
  page_status?: string;
  /** Pages dated after this page that mention it, newest first, bounded. `context_pack` cards only (mentions/newer-mentions.ts). */
  newer_mentions?: NewerMentions;
  /** Distinct pages with any inbound link (every link source, mentions included). `entity` verb only. */
  referenced_by_count?: number;
  /** Those pages grouped by pack-canonical type, newest first; capped per group and per card. `entity` verb only. */
  referenced_by?: ReferenceGroupView[];
  /**
   * The referring pages of the enrolled record types (`entity.record_types`), one group per type, newest page date first
   * (the order never says which record governs). `entity` and `context_pack` only, and only when types are enrolled.
   */
  records?: RecordGroupView[];
  /** `context_pack` cards: the same reference fields for each identity sibling, side by side, never merged. */
  sibling_records?: Array<{ slug: string; title: string } & RowReferences>;
  /** The reference count and records could not be read (deadline or failure); unread, not empty. */
  references_unavailable?: ReferencesUnavailable;
  /** Whether every page in this source has been scanned for this entity's names. `entity` verb only. */
  coverage?: MentionCoverage;
  /** Parallel to `aka`: each entry's origin (frontmatter, declared, subject) and the page that declares it. `entity` verb only. */
  aka_sources?: CardIdentity['aka_sources'];
  /** Pages naming the same subject under another title prefix, with their own aliases; never merged into this card. `entity` verb only. */
  identity_siblings?: CardIdentity['identity_siblings'];
  /** Verbatim lines of this page and its siblings that may carry other names (label lines, codes, declarations), with the page slug. `entity` verb only. */
  identity_excerpt?: CardIdentity['identity_excerpt'];
  /** Pages whose qualifying lines did not fit the excerpt budget. */
  identity_excerpt_omitted?: string[];
  /** What `aka` covers and which names to search before a history or as-of answer. `entity` verb only. */
  alias_guidance?: CardIdentity['alias_guidance'];
  /** #5575 A6 (additive): the entity page's trust tier and short write origin. */
  trust_tier?: TrustTier;
  origin?: string;
  /** #5575 ENG-15 (additive): the page is quarantined; renderers wrap its summary as external data. */
  quarantined?: true;
  /** #5575 CEO-20 (additive): the entity page carries an unconfirmed instruction-family write-gate flag. */
  unconfirmed?: true;
  /** #7160 (additive): the card resolved through a name variant (nickname, initial, title, reordering, typo or surname), not an exact name. */
  match?: EntityNameMatch;
  /** #7160 (additive): title-prefixed person pages that likely name the same person (reported only, never merged). `entity` verb only. */
  possible_duplicates?: PossibleDuplicate[];
  /** #7161 (additive): on a card with no backlinks and no facts while mention coverage is incomplete, pages whose text contains the title (unlinked text matches, newest first). `entity` verb only. */
  text_mentions?: TextMentions;
}

export interface ReferenceGroupView {
  canonical_type: string;
  total: number;
  rows: Array<Omit<ReferenceRow, 'source_id'>>;
  /** The call that returns the rest of a truncated group (`requires_surface` when this connection cannot call it). */
  next?: { tool: 'get_backlinks'; arguments: Record<string, unknown>; requires_surface?: 'starter' };
}

/** #7160: how a name-variant arm matched (absent on alias, exact and suffix hits). */
export interface EntityNameMatch {
  kind: NameMatchKind;
  /** The name as asked. */
  via: string;
}

export interface EntitySuggestion {
  slug: string;
  title: string;
  create_safety: string;
  /** #6723: the source the suggested page lives in. */
  source_id?: string;
}

export interface EntityCardResult {
  found: boolean;
  card?: EntityCard;
  suggestions?: EntitySuggestion[];
  /** On a miss with `includeReferences`: the source's mention coverage (a miss may be a not-yet-indexed name). */
  coverage?: MentionCoverage;
  /** #7161: on a miss with `includeReferences`, pages whose text contains the name (unlinked text matches, newest first). */
  text_mentions?: TextMentions;
  /** #7160: on a miss, the name matched several entity pages as a variant (listed in suggestions); pick one rather than create a page. */
  ambiguous?: true;
  /** #6723: the source of the resolved page (absent on a miss). */
  source_id?: string;
  /**
   * #6724: the full fact rows the card read (newest first, visibility and
   * eligibility already applied), for context_pack's `entity_facts`. Never part
   * of the card: the `entity` verb does not return it.
   */
  factRows?: FactRow[];
}

export interface EntityCardOpts {
  remote: boolean;
  /**
   * GST-2957: the reader's OperationContext.remote, for the edges' stored link contexts (worldLinkContexts). context_pack
   * builds cards with `remote` set for any caller without include_private; absent, `remote` stands for it.
   */
  readerRemote?: boolean;
  /**
   * #6723: the sources to resolve the name in, probed in this order (home
   * first); the first source with a hit owns the card and every read behind
   * it. Absent: the positional source alone.
   */
  sources?: readonly string[];
  /**
   * Compute `referenced_by`, `referenced_by_count` and `coverage` (the `entity`
   * verb). Ambient callers (context_pack, delta) leave it off.
   */
  includeReferences?: boolean;
  /** The serving surface ceiling; on `verbs` a continuation names the starter surface. */
  surfaceCeiling?: 'verbs' | 'starter' | 'full';
  /** Receives the degraded notice when the card's references or records could not be read. */
  emitNotice?: (n: Notice) => void;
  /**
   * #5575 (ENG-8, CEO-20): the eligibility for the card's facts and timeline
   * rows. Always hides quarantined-page projections and rows awaiting
   * re-derivation; a proactive caller (context_pack, delta) passes its floor
   * and activation control.
   */
  eligibility?: ReadEligibility;
  /**
   * #5575 (ENG-8, ENG-15): leave out a page the content-quality gate
   * quarantined, as if it did not exist (no suggestion names it). Proactive
   * callers always pass it unless an authorized `include_quarantined` asked;
   * the entity verb passes it for remote callers, like get_page.
   */
  omitQuarantined?: boolean;
  /**
   * #7160: run the name-variant arm after the precision arms miss. The
   * `entity` verb and `entity names` ask for it; proactive cards
   * (context_pack, delta) never resolve a guessed name.
   */
  variants?: boolean;
}

export interface CardPageRow {
  slug: string;
  // v0.43 merge: retrieval-reflex's exported PageRow (safeSynopsis's param)
  // now requires source_id (federated push-context wave #2095). The card row
  // carries it too so it remains assignable.
  source_id: string;
  title: string;
  type: string | null;
  frontmatter: Record<string, unknown> | null;
  compiled_truth: string | null;
  updated_at: Date | string | null;
  last_retrieved_at: Date | string | null;
}

/** The card's page-row projection over `pages` (bounded body prefix, last retrieval). */
const CARD_ROW_COLUMNS = `slug, source_id, title, type, frontmatter, ${boundedBodyPrefixSql('pages')} AS compiled_truth, updated_at,
              GREATEST(last_retrieved_at, (SELECT r.last_retrieved_at FROM page_retrievals r WHERE r.page_id = pages.id)) AS last_retrieved_at`;

/** Resolution arm rank: lower = higher confidence (frozen precedence ladder). */
const ARM_ALIAS = 0;
const ARM_EXACT = 1;
const ARM_SUFFIX = 2;

/**
 * The per-call invariants of a name lookup: whether this caller is kept from
 * private pages (#4352: untrusted callers never resolve a `visibility:
 * private` page into a card or a near-miss suggestion; local callers are
 * unchanged), the mention policy and source pack (undefined policy: it could
 * not be read), and the pack's linkable entity types (the exact-title
 * tie-break; empty without a policy). A batch reads them once.
 */
export interface EntityLookupScope {
  excludePrivate: boolean;
  entityTypes: ReadonlySet<string>;
  policy: MentionPolicy | undefined;
  pack: PackTypes | null;
}

export async function entityLookupScope(engine: BrainEngine, sourceId: string, remote: boolean): Promise<EntityLookupScope> {
  const { resolveExcludePrivatePages } = await import('../search/private-visibility.ts');
  const excludePrivate = await resolveExcludePrivatePages(engine, remote ? undefined : false);
  const policy = await readMentionPolicy(engine).catch(() => undefined);
  const pack = await loadSourcePack(engine, sourceId);
  return { excludePrivate, entityTypes: new Set(policy ? linkableTypesFor(pack, policy) : []), policy, pack };
}

/**
 * Candidate selection for one name: `hit` with the best page row (its
 * bounded, withdrawal-overlaid `compiled_truth` prefix included) and up to SUGGESTION_CAP runners-up; `miss` with
 * keyword near-miss suggestions; `withheld` when every match is a quarantined
 * page `omitQuarantined` leaves out (no suggestion names it).
 */
export type EntityCandidates =
  | { kind: 'hit'; row: CardPageRow; runnersUp: EntitySuggestion[]; match?: EntityNameMatch }
  | { kind: 'miss'; suggestions: EntitySuggestion[]; ambiguous?: true }
  | { kind: 'withheld' };

/** Resolve a trimmed, non-empty name to its candidates. Every arm is fail-soft. */
export async function selectEntityCandidates(
  engine: BrainEngine,
  sourceId: string,
  trimmed: string,
  scope: EntityLookupScope,
  opts: { omitQuarantined?: boolean; suggest?: boolean; variants?: boolean } = {},
): Promise<EntityCandidates> {
  const { privatePagesFilterForCaller } = await import('../search/private-visibility.ts');
  // Predicate text lives ONCE (private-visibility.ts) — both card queries
  // below select `FROM pages` unaliased, so qualify with the table name.
  const privatePredicate = scope.excludePrivate ? ` AND ${privatePagesFilterForCaller('pages')}` : '';

  const norm = normalizeAlias(trimmed);
  const titleLc = trimmed.toLowerCase();
  // Two exact-slug candidates: the slugified form for free-text names AND the
  // raw input — a caller passing an already-namespaced slug
  // ("people/alice-example") must hit exactly (slugify flattens the slash).
  const slug = slugify(trimmed);
  const exactSlugs = [...new Set([slug, trimmed].filter(Boolean))];

  // Candidate slugs with their best arm rank.
  const rankBySlug = new Map<string, number>();
  const consider = (s: string, rank: number) => {
    if (!s) return;
    const prev = rankBySlug.get(s);
    if (prev === undefined || rank < prev) rankBySlug.set(s, rank);
  };

  // Arm 1 — alias-first. Guarded: pre-migration brains lack page_aliases.
  if (norm) {
    try {
      const aliasMap = await engine.resolveAliases([norm], { sourceId });
      for (const hit of aliasMap.get(norm) ?? []) consider(hit.slug, ARM_ALIAS);
    } catch {
      /* no page_aliases table — degrade to arm 2 [E3] */
    }
  }

  // Arm 2 — exact title / exact slug / slug-suffix, with the columns the
  // card's tie-break needs. Guarded like the reflex.
  let rows: CardPageRow[] = [];
  try {
    rows = await engine.executeRaw<CardPageRow>(
      `SELECT ${CARD_ROW_COLUMNS}
         FROM pages
        WHERE deleted_at IS NULL
          AND source_id = $1
          AND ( lower(title) = $2
             OR slug = ANY($3::text[])
             OR slug LIKE $4 )${privatePredicate}`,
      [sourceId, titleLc, exactSlugs, `%/${slug || trimmed}`],
    );
  } catch {
    rows = [];
  }
  const rowBySlug = new Map<string, CardPageRow>();
  for (const r of rows) {
    rowBySlug.set(r.slug, r);
    const isExact = (r.title ?? '').toLowerCase() === titleLc || exactSlugs.includes(r.slug);
    consider(r.slug, isExact ? ARM_EXACT : ARM_SUFFIX);
  }

  // Hydrate alias-resolved slugs that arm 2 didn't fetch.
  const missing = [...rankBySlug.keys()].filter(s => !rowBySlug.has(s));
  if (missing.length) {
    try {
      const extra = await engine.executeRaw<CardPageRow>(
        `SELECT ${CARD_ROW_COLUMNS}
           FROM pages
          WHERE deleted_at IS NULL AND source_id = $1 AND slug = ANY($2::text[])${privatePredicate}`,
        [sourceId, missing],
      );
      for (const r of extra) rowBySlug.set(r.slug, r);
    } catch {
      /* stale alias rows — drop */
    }
  }

  // Rank candidates: arm rank asc. Inside the precision arm an explicit slug
  // stays stronger than title inference; otherwise exact-title collisions
  // prefer a linkable entity page (the source pack's entity types) over
  // transcript/note containers. Recency remains the final tie-break within
  // the same match shape.
  const entityTypes = scope.entityTypes;
  const candidates = [...rankBySlug.entries()]
    .map(([s, rank]) => ({ slug: s, rank, row: rowBySlug.get(s) }))
    .filter((c): c is { slug: string; rank: number; row: CardPageRow } => c.row !== undefined)
    .sort((a, b) =>
      a.rank - b.rank
      || (a.rank === ARM_EXACT
        ? exactMatchPreference(a.row, exactSlugs, entityTypes) - exactMatchPreference(b.row, exactSlugs, entityTypes)
        : 0)
      || lastTouchedMs(b.row) - lastTouchedMs(a.row));

  if (opts.omitQuarantined && candidates.some(c => isQuarantined(c.row.frontmatter))) {
    const live = candidates.filter(c => !isQuarantined(c.row.frontmatter));
    if (live.length === 0) return { kind: 'withheld' };
    candidates.splice(0, candidates.length, ...live);
  }
  if (candidates.length === 0) {
    // #7160: the name-variant arm, after every precision arm missed.
    const variants = opts.variants && await nameVariantsEnabled(engine)
      ? await resolveNameVariant<CardPageRow>(engine, sourceId, trimmed, {
        selectColumns: CARD_ROW_COLUMNS, privatePredicate, entityTypes: scope.entityTypes, omitQuarantined: opts.omitQuarantined,
        retirementPrivacy: scope.excludePrivate ? ` AND ${privatePagesFilterForCaller('p')}` : '' })
      : { matches: [] };
    const variantSuggestions = (matches: typeof variants.matches): EntitySuggestion[] => matches.map(m => ({
      slug: m.row.slug, title: m.row.title ?? m.row.slug, create_safety: 'exists', source_id: sourceId }));
    if (variants.hit) {
      const hit = variants.hit;
      const [row] = await overlaidBoundedRows(engine, [hit.row]);
      return { kind: 'hit', row, match: { kind: hit.kind, via: trimmed },
        runnersUp: variantSuggestions(variants.matches.filter(m => m.row.slug !== hit.row.slug)).slice(0, SUGGESTION_CAP) };
    }
    const ambiguous = variants.matches.length > 0 ? { ambiguous: true as const } : {};
    if (opts.suggest === false) return { kind: 'miss', suggestions: [], ...ambiguous };
    const seen = new Set<string>();
    const suggestions = [...variantSuggestions(variants.matches), ...await nearMissSuggestions(engine, sourceId, trimmed, scope)]
      .filter(x => !seen.has(x.slug) && (seen.add(x.slug), true));
    return { kind: 'miss', suggestions: suggestions.slice(0, SUGGESTION_CAP), ...ambiguous };
  }

  // Large pages: the hit carries a bounded, withdrawal-overlaid body prefix (its summary and lead read only that).
  const [row] = await overlaidBoundedRows(engine, [candidates[0].row]);
  return {
    kind: 'hit',
    row,
    runnersUp: candidates.slice(1, 1 + SUGGESTION_CAP).map(c => ({
      slug: c.slug,
      title: c.row.title ?? c.slug,
      // A page that resolved through the precision arms exists by definition.
      create_safety: 'exists',
      source_id: sourceId,
    })),
  };
}

/**
 * #6723: resolve a name across sources in the given order (home first, then
 * the rest of the caller's grant). The first source with a hit owns the
 * result; a source is read with its own lookup scope (pack, linkable types).
 * Without a hit anywhere, the first source's miss (its near-miss suggestions)
 * or withheld result is returned. Sources outside the list are never read.
 */
export async function selectAcrossSources(
  engine: BrainEngine,
  sources: readonly string[],
  trimmed: string,
  remote: boolean,
  opts: { omitQuarantined?: boolean; scopes?: Map<string, Promise<EntityLookupScope>>; variants?: boolean } = {},
): Promise<{ sourceId: string; scope: EntityLookupScope; selected: EntityCandidates }> {
  let first: { sourceId: string; scope: EntityLookupScope; selected: EntityCandidates } | undefined;
  const variantHits: Array<{ sourceId: string; scope: EntityLookupScope; selected: Extract<EntityCandidates, { kind: 'hit' }> }> = [];
  let variantAmbiguous = false;
  for (const sourceId of sources) {
    if (opts.scopes && !opts.scopes.has(sourceId)) opts.scopes.set(sourceId, entityLookupScope(engine, sourceId, remote));
    const scope = await (opts.scopes?.get(sourceId) ?? entityLookupScope(engine, sourceId, remote));
    const selected = await selectEntityCandidates(engine, sourceId, trimmed, scope, { omitQuarantined: opts.omitQuarantined, suggest: first === undefined, variants: opts.variants });
    // #7160: an exact hit in any source beats a name-variant guess, and a guess must be unique across every source read.
    if (selected.kind === 'hit' && !selected.match) return { sourceId, scope, selected };
    if (selected.kind === 'hit') variantHits.push({ sourceId, scope, selected });
    if (selected.kind === 'miss' && selected.ambiguous) variantAmbiguous = true;
    first ??= { sourceId, scope, selected };
  }
  if (variantHits.length === 1 && !variantAmbiguous) return variantHits[0]!;
  if (variantHits.length && first) {
    const hitSuggestions = variantHits.map(v => ({ slug: v.selected.row.slug, title: v.selected.row.title ?? v.selected.row.slug, create_safety: 'exists', source_id: v.sourceId }));
    const rest = first.selected.kind === 'miss' ? first.selected.suggestions : [];
    return { ...first, selected: { kind: 'miss', ambiguous: true, suggestions: [...hitSuggestions, ...rest].slice(0, SUGGESTION_CAP) } };
  }
  return first!;
}

export async function buildEntityCard(
  engine: BrainEngine,
  sourceId: string,
  name: string,
  opts: EntityCardOpts,
): Promise<EntityCardResult> {
  const trimmed = (name ?? '').trim();
  if (!trimmed) return { found: false, suggestions: [] };

  // Covers entity, context_pack, and delta (all route through buildEntityCard).
  // #6723: the source with the hit owns the card; every read below uses it.
  const sources = opts.sources?.length ? opts.sources : [sourceId];
  const { sourceId: hitSource, scope, selected } = await selectAcrossSources(engine, sources, trimmed, opts.remote, { omitQuarantined: opts.omitQuarantined, variants: opts.variants });
  if (selected.kind === 'withheld') return { found: false, suggestions: [] };
  if (selected.kind === 'miss') {
    const ambiguous = selected.ambiguous ? { ambiguous: selected.ambiguous } : {};
    if (!opts.includeReferences) return { found: false, suggestions: selected.suggestions, ...ambiguous };
    const textMentions = await readTextMentions(engine, sources, trimmed, { remote: opts.remote, excludePrivate: scope.excludePrivate, omitQuarantined: opts.omitQuarantined });
    return {
      found: false, suggestions: selected.suggestions,
      coverage: await readMentionCoverage(engine, [...sources]).catch(() => undefined),
      ...(textMentions?.total || textMentions?.unread ? { text_mentions: textMentions } : {}),
      ...ambiguous,
    };
  }

  const { row, runnersUp, match } = selected;
  const { card, facts: factRows } = await assembleCard(engine, hitSource, row, opts.remote, scope.excludePrivate, opts.eligibility ?? {}, opts.readerRemote ?? opts.remote);
  if (match) card.match = match;
  if (opts.includeReferences) {
    Object.assign(card, await cardReferences(engine, hitSource, row, opts, scope.excludePrivate, scope.entityTypes),
      await readCardIdentity(engine, hitSource, row, { excludePrivate: scope.excludePrivate, excludeQuarantined: opts.omitQuarantined === true, surfaceCeiling: opts.surfaceCeiling, aka: card.aka, hideHeld: (await import('../search/private-visibility.ts')).worldOnlyFacts(opts.remote) }));
    await attachCardRecords(engine, hitSource, card, opts, scope.excludePrivate);
    if (await nameVariantsEnabled(engine)) {
      const { privatePagesFilterForCaller } = await import('../search/private-visibility.ts');
      const duplicates = await readPossibleDuplicates<CardPageRow>(engine, hitSource, row, {
        selectColumns: CARD_ROW_COLUMNS, entityTypes: scope.entityTypes, omitQuarantined: opts.omitQuarantined,
        privatePredicate: scope.excludePrivate ? ` AND ${privatePagesFilterForCaller('pages')}` : '',
        retirementPrivacy: scope.excludePrivate ? ` AND ${privatePagesFilterForCaller('p')}` : '' });
      if (duplicates.length) card.possible_duplicates = duplicates;
    }
    // #7161: a thin card while mentions are behind may be a stale stub; show where the name appears in text.
    if (card.backlink_count === 0 && card.active_fact_count === 0 && card.coverage && card.coverage.state !== 'complete') {
      const textMentions = await readTextMentions(engine, [hitSource], row.title || trimmed,
        { remote: opts.remote, excludePrivate: scope.excludePrivate, omitQuarantined: opts.omitQuarantined, exclude: [row.slug] });
      if (textMentions?.total || textMentions?.unread) card.text_mentions = textMentions;
    }
  }
  return {
    found: true,
    card,
    source_id: hitSource,
    factRows,
    ...(runnersUp.length ? { suggestions: runnersUp } : {}),
  };
}

/**
 * The `entity` verb's reference fields: every page linking here (mentions
 * included), grouped by pack-canonical type with the continuation for a
 * truncated group, and the source's mention coverage. Fail-soft: a failed
 * read leaves the card without them rather than failing the lookup.
 */
async function cardReferences(engine: BrainEngine, sourceId: string, row: CardPageRow, opts: EntityCardOpts, excludePrivate: boolean,
  entityTypes: ReadonlySet<string>): Promise<Pick<EntityCard, 'referenced_by_count' | 'referenced_by' | 'coverage' | 'references_unavailable'>> {
  try {
    const { pack } = await loadLinkableTypes(engine, sourceId);
    const { total, groups } = await readReferrerGroups(engine, { slug: row.slug, sourceId, referrerSources: [sourceId], excludePrivate, pack,
      keepVisibility: opts.remote ? ['world'] : ['private', 'world'], eligibility: opts.eligibility });
    let coverage = await readMentionCoverage(engine, [sourceId]);
    if (coverage.state !== 'disabled' && !entityTypes.has(row.type ?? '')) coverage = { ...coverage, state: 'type_not_linkable', degraded: true };
    const referenced_by = groups.map((g): ReferenceGroupView => {
      const rows = g.rows.map(({ source_id: _s, ...rest }) => rest);
      if (g.rows.length >= g.total) return { canonical_type: g.canonical_type, total: g.total, rows };
      const last = g.rows[g.rows.length - 1];
      return { canonical_type: g.canonical_type, total: g.total, rows, next: { tool: 'get_backlinks', arguments: {
        slug: row.slug, source_id: sourceId, type: g.canonical_type, group: 'page', limit: PAGE_DEFAULT_LIMIT,
        ...(last ? { cursor: encodeCursor(last) } : {}) }, ...(opts.surfaceCeiling === 'verbs' ? { requires_surface: 'starter' as const } : {}) } };
    });
    return { referenced_by_count: total, referenced_by, coverage };
  } catch {
    opts.emitNotice?.(referencesUnavailableNotice('read_failed'));
    return { references_unavailable: 'read_failed' };
  }
}

/** The full card's record view for the page and each identity sibling (records only: the card has its own count). */
async function attachCardRecords(engine: BrainEngine, sourceId: string, card: EntityCard, opts: EntityCardOpts, excludePrivate: boolean): Promise<void> {
  const siblings = card.identity_siblings?.pages ?? [];
  const refs = await readRowReferences(engine, sourceId, [card.entity.slug, ...siblings.map(p => p.slug)].map(slug => ({ slug, sourceId })),
    { remote: opts.remote, excludePrivate, surfaceCeiling: opts.surfaceCeiling, eligibility: opts.eligibility, surface: 'full_card', emitNotice: opts.emitNotice });
  const [own, ...rest] = refs.rows;
  if (own?.records) card.records = own.records;
  siblings.forEach((p, i) => { if (rest[i]?.records) Object.assign(p, { records: rest[i]!.records }); });
  if (!own?.references_unavailable || card.references_unavailable) return;
  card.references_unavailable = own.references_unavailable;
  if (refs.notice) opts.emitNotice?.(refs.notice);
}

async function assembleCard(
  engine: BrainEngine,
  sourceId: string,
  row: CardPageRow,
  remote: boolean,
  excludePrivate: boolean,
  eligibility: ReadEligibility,
  readerRemote: boolean,
): Promise<{ card: EntityCard; facts: FactRow[] }> {
  const pageSlug = row.slug;
  const { privatePagesFilterForCaller, privateLinkOriginFilterForCaller, privateFactFilterForReader, worldOnlyFacts } = await import('../search/private-visibility.ts');
  const worldOnly = worldOnlyFacts(remote);
  const visibility = worldOnly ? (['world'] as ('private' | 'world')[]) : undefined;
  // Facts saved about this entity may sit under a sibling page or the bare subject slug (siblings.ts).
  const factSlugs = await factEntitySlugs(engine, sourceId, pageSlug, { excludePrivate }).catch(() => [pageSlug]);
  const inboundPrivacy = (excludePrivate
    ? ` AND ${privatePagesFilterForCaller('f')} AND ${privateLinkOriginFilterForCaller('l')}`
    : '') + ` AND (l.origin_page_id IS NULL OR EXISTS (SELECT 1 FROM pages lo WHERE lo.id = l.origin_page_id AND lo.deleted_at IS NULL${remote ? ' AND lo.source_id = $2' : ''}))`;

  // Parallel depth-1 reads — every arm individually fail-soft so a partial
  // brain (no aliases, no timeline) still returns a card.
  //
  // [ship P1.2] Incoming edges + backlink_count are SOURCE-SAFE on BOTH sides.
  // engine.getBacklinks(slug,{sourceId}) only scopes the TARGET page's source,
  // so a foreign-source page linking to a same-named entity would leak its
  // slug; engine.getBacklinkCounts counts inbound from ALL sources. We run
  // a both-sides-scoped query here (f.source_id = t.source_id = this source),
  // mentions excluded (matching the backlink-count convention). Outgoing edges
  // (getLinks) are the entity's OWN declared links — from-side scoped for the
  // trusted local caller; an untrusted caller reads them through the engine's
  // all-endpoints branch (`sourceIds`), so an edge the source policy admitted
  // into another source (#4680) never shows that source's slug on the card.
  // The referrer must also be live and, for an untrusted caller,
  // readable: the same private-page and private-origin predicates get_backlinks
  // applies, so a private or derived page never surfaces its slug, its
  // links.context sentence, or a count. An edge whose origin page is deleted
  // (or, for an untrusted caller, in another source) is left out the same way.
  const [aka, outLinks, inEdges, backlinkCount, timeline, facts, activeFactCount] = await Promise.all([
    readAka(engine, sourceId, pageSlug),
    engine.getLinks(pageSlug, { ...(remote ? { sourceIds: [sourceId] } : { sourceId }), excludePrivate, temporal: { status: 'all' } }).catch(() => []),
    engine
      .executeRaw<{ from_slug: string; link_type: string; context: string | null }>(
        `SELECT f.slug AS from_slug, l.link_type, l.context${TEMPORAL_LINK_SELECT_SQL}
           FROM links l
           JOIN pages f ON f.id = l.from_page_id
           JOIN pages t ON t.id = l.to_page_id
           ${temporalLinkJoinSql('l', excludePrivate)}
          WHERE t.slug = $1 AND t.source_id = $2 AND f.source_id = $2 AND f.deleted_at IS NULL
            AND COALESCE(l.link_source, '') <> 'mentions'${inboundPrivacy}
          ORDER BY l.id`,
        [pageSlug, sourceId],
      )
      .then(rs => rs.map(r => annotateTemporalRow(r)))
      .catch(() => [] as Array<{ from_slug: string; link_type: string; context: string | null } & TemporalAnnotation>),
    engine
      .executeRaw<{ n: string | number }>(
        `SELECT COUNT(*) AS n
           FROM links l
           JOIN pages f ON f.id = l.from_page_id
           JOIN pages t ON t.id = l.to_page_id
          WHERE t.slug = $1 AND t.source_id = $2 AND f.source_id = $2 AND f.deleted_at IS NULL
            AND COALESCE(l.link_source, '') <> 'mentions'${inboundPrivacy}`,
        [pageSlug, sourceId],
      )
      .then(rs => Number(rs[0]?.n ?? 0))
      .catch(() => 0),
    engine.getTimeline(pageSlug, { limit: 5, sourceId, excludePrivate, eligibility }).catch(() => []),
    Promise.all(factSlugs.map(slug => engine.listFactsByEntity(sourceId, slug, {
      activeOnly: true,
      limit: FACT_FETCH_CAP,
      ...(visibility ? { visibility } : {}),
      excludePrivate,
      eligibility,
    })))
      .then(lists => lists.flat().sort((a, b) => factTime(b) - factTime(a)).slice(0, FACT_FETCH_CAP))
      .catch(() => [] as FactRow[]),
    // Exact active-fact count: the payload fetch above is capped at
    // FACT_FETCH_CAP, so facts.length silently reports the cap for bigger
    // entities. Same predicate as the fetch (active + source + caller
    // visibility), indexed COUNT instead of rows. Fail-soft to null so a
    // count failure degrades to the capped payload length, never to 0.
    engine
      .executeRaw<{ n: string | number }>(
        `SELECT COUNT(*) AS n
           FROM facts
          WHERE source_id = $1 AND entity_slug = ANY($2::text[])
            AND expired_at IS NULL${worldOnly ? ` AND visibility = 'world'` : ''}${excludePrivate ? ` AND ${privateFactFilterForReader('facts')}` : ''}
            AND ${projectionEligibleSql('facts', 'facts', eligibility)}`,
        [sourceId, factSlugs],
      )
      .then(rs => Number(rs[0]?.n ?? 0))
      .catch(() => null),
  ]);

  // Live relationships first so ended ones never push a current edge past the cap.
  const rank = ({ status, type }: EntityCardEdge) => (status === 'live' || status === 'disputed' ? 0
    : status === 'event' || status === 'reference' || !status || LIVENESS_EXEMPT_LINK_TYPES.includes(type) ? 1 : 2);
  const edgeOf = (l: { link_type: string; context?: string | null } & Partial<TemporalAnnotation>, direction: 'out' | 'in', slug: string): EntityCardEdge => {
    const last = l.stints?.[l.stints.length - 1];
    return {
      type: l.link_type, direction, slug, context: l.context || null,
      ...(l.status ? { status: l.status } : {}),
      ...(last ? { since: last.from, until: last.until } : {}),
    };
  };
  const outCandidates = (await worldLinkContexts(engine, readerRemote, (outLinks as Array<Link & Partial<TemporalAnnotation>>)
    .filter(l => l.link_source !== 'mentions'), storedEdge))
    .map(l => edgeOf(l, 'out', l.to_slug));
  const inCandidates = (await worldLinkContexts(engine, readerRemote, inEdges, l => ({ from: { sourceId, slug: l.from_slug }, to: { sourceId, slug: pageSlug }, linkType: l.link_type })))
    .map(l => edgeOf(l as typeof l & Partial<TemporalAnnotation>, 'in', l.from_slug));
  const edges: EntityCardEdge[] = [
    ...[...outCandidates].sort((a, b) => rank(a) - rank(b)),
    ...[...inCandidates].sort((a, b) => rank(a) - rank(b)),
  ].slice(0, EDGE_CAP);
  const summary = safeSynopsis(row, { keepVisibility: remote ? ['world'] : ['private', 'world'] });
  const relationshipNote = await loadRelationshipNotes(engine, [{ slug: pageSlug, source_id: sourceId, summary }], { excludePrivate })
    .then(m => m.get(relationshipNoteKey(sourceId, pageSlug))).catch(() => undefined);

  // Open threads (best-effort v1): open-loop rows first (v0.47 — richest:
  // direction, due, loop_id), then active commitment facts NOT already
  // represented by a loop, then recent timeline entries; capped together.
  const openThreads: EntityOpenThread[] = [];
  const loopFactIds = new Set<number>();
  try {
    // Zero-LLM, indexed lookup — stays inside the p99<100ms budget. A loop
    // belongs to this card when its counterparty page is THIS (source, slug):
    // a Gmail-source loop whose person page lives in `default` shows on the
    // default card, a pre-v236 row (NULL counterparty source) on its own
    // source's card (#5504). Loops carry no visibility or grant of their own
    // (summaries derive from private mail, often another source), so a
    // world-only card never reads them; open_loops serves remote callers
    // inside their grant.
    const loopRows = remote ? [] : await engine.executeRaw<{
      id: number;
      loop_type: string;
      summary: string;
      due_at: string | null;
      last_activity_at: string;
      fact_id: number | null;
    }>(
      `SELECT id, loop_type, summary, due_at, last_activity_at, fact_id
       FROM open_loops
       WHERE status = 'open' AND counterparty_slug = $1
         AND COALESCE(counterparty_source_id, source_id) = $2
       ORDER BY last_activity_at DESC
       LIMIT ${OPEN_THREADS_CAP}`,
      [pageSlug, sourceId],
    );
    for (const l of loopRows) {
      if (l.fact_id !== null) loopFactIds.add(Number(l.fact_id));
      const direction: EntityOpenThread['direction'] =
        l.loop_type === 'commitment_owed_by_me'
          ? 'owed_by_me'
          : l.loop_type === 'commitment_owed_to_me'
            ? 'owed_to_me'
            : l.loop_type === 'unanswered_inbound'
              ? 'my_turn'
              : 'their_turn';
      openThreads.push({
        kind: 'commitment',
        text: l.summary,
        date: typeof l.last_activity_at === 'string' ? l.last_activity_at : new Date(l.last_activity_at).toISOString(),
        direction,
        due: l.due_at ? (typeof l.due_at === 'string' ? l.due_at : new Date(l.due_at).toISOString()) : null,
        counterparty: pageSlug,
        status: 'open',
        loop_id: Number(l.id),
      });
      if (openThreads.length >= OPEN_THREADS_CAP) break;
    }
  } catch {
    /* pre-v144 brains have no open_loops table — facts path below covers it */
  }
  for (const f of facts) {
    if (openThreads.length >= OPEN_THREADS_CAP) break;
    if (f.kind !== 'commitment') continue;
    if (f.id !== undefined && loopFactIds.has(f.id)) continue; // already surfaced via its loop
    openThreads.push({ kind: 'commitment', text: f.fact, date: f.valid_from?.toISOString() ?? null, ...trustFields(f.trust_tier, f.write_origin) });
  }
  if (openThreads.length < OPEN_THREADS_CAP) {
    const cutoff = Date.now() - OPEN_THREAD_TIMELINE_WINDOW_DAYS * 24 * 60 * 60 * 1000;
    for (const t of timeline) {
      // Both engines TYPE this as string, but PGLite returns a Date object at
      // runtime for the DATE column. Normalize at the public-card boundary so
      // the frozen string|null contract holds for in-process consumers too.
      const date = toIso(t.date);
      const ts = date === null ? NaN : Date.parse(date);
      if (!Number.isFinite(ts) || ts < cutoff) continue;
      const raw = t as unknown as { trust_tier?: unknown; write_origin?: unknown };
      openThreads.push({ kind: 'recent_event', text: t.summary, date, ...trustFields(raw.trust_tier, raw.write_origin) });
      if (openThreads.length >= OPEN_THREADS_CAP) break;
    }
  }

  const pageTrust = (await loadPageTrust(engine, [{ source_id: sourceId, slug: pageSlug }]).catch(() => null))?.byKey.get(`${sourceId}\u0000${pageSlug}`);
  return { facts, card: {
    entity: { slug: pageSlug, title: row.title ?? pageSlug, type: row.type ?? null, source_id: sourceId },
    ...(pageTrust ?? { trust_tier: 'unknown' as const, origin: 'unrecorded' }),
    ...(isQuarantined(row.frontmatter) ? { quarantined: true as const } : {}),
    aka,
    // v0.45.7: summary widens in lockstep with the card's fact visibility —
    // remote (world-only) keeps ['world']; a local include_private card widens.
    summary,
    last_touched: {
      updated_at: toIso(row.updated_at),
      last_retrieved_at: toIso(row.last_retrieved_at),
      last_timeline_date: timeline.length ? toIso(timeline[0].date) : null,
    },
    open_threads: openThreads,
    edges,
    backlink_count: backlinkCount,
    active_fact_count: activeFactCount ?? facts.length,
    ...(relationshipNote ? { relationship_note: relationshipNote } : {}),
    ...(facts.length ? { recent_facts: facts.slice(0, RECENT_FACTS_CAP).map(f => ({
      id: String(f.id), fact: f.fact, kind: f.kind, valid_from: f.valid_from ? toIso(f.valid_from as Date | string) : null,
      ...(f.entity_slug && f.entity_slug !== pageSlug ? { entity_slug: f.entity_slug } : {}),
    })) } : {}),
  } };
}

/** The card's `aka`: the page's normalized aliases (page_aliases reverse lookup); empty on a pre-migration brain. */
export async function readAka(engine: BrainEngine, sourceId: string, slug: string): Promise<string[]> {
  return engine
    .executeRaw<{ alias_norm: string }>(
      `SELECT alias_norm FROM page_aliases WHERE source_id = $1 AND slug = $2 ORDER BY alias_norm`,
      [sourceId, slug],
    )
    .then(rs => rs.map(r => r.alias_norm))
    .catch(() => [] as string[]);
}

function factTime(f: FactRow): number {
  return toMs((f.valid_from ?? f.created_at ?? null) as Date | string | null);
}

/**
 * Near-miss suggestions on a total miss (E5 delight): keyword search top-N
 * with evidence-derived create_safety so a typo'd name becomes a next move
 * instead of a dead end. Zero LLM; fail-soft to [].
 */
async function nearMissSuggestions(
  engine: BrainEngine,
  sourceId: string,
  name: string,
  scope: Pick<EntityLookupScope, 'excludePrivate' | 'entityTypes'>,
): Promise<EntitySuggestion[]> {
  try {
    // #7160: over-fetch keyword hits and keep entity pages only; index, digest and note pages are never "did you mean".
    const raw = await engine.searchKeyword(name, { limit: NEAR_MISS_POOL, sourceId, excludePrivate: scope.excludePrivate });
    const results = (raw as SearchResult[])
      .filter((r, i, all) => (isIdentityEntity(r.slug, r.type) || scope.entityTypes.has(r.type ?? '')) && all.findIndex(o => o.slug === r.slug) === i)
      .slice(0, SUGGESTION_CAP);
    // #3783 — direct FTS path: every row is a keyword hit by construction.
    markKeywordHits(results);
    stampEvidence(results);
    return results.map(r => ({
      slug: r.slug,
      title: r.title ?? r.slug,
      create_safety: r.create_safety ?? 'unknown',
      source_id: r.source_id ?? sourceId,
    }));
  } catch {
    return [];
  }
}

function lastTouchedMs(row: CardPageRow): number {
  const u = toMs(row.updated_at);
  const l = toMs(row.last_retrieved_at);
  return Math.max(u, l);
}

function toMs(v: Date | string | null): number {
  if (v == null) return 0;
  const ms = v instanceof Date ? v.getTime() : Date.parse(v);
  return Number.isFinite(ms) ? ms : 0;
}

function toIso(v: Date | string | null): string | null {
  const ms = toMs(v);
  return ms > 0 ? new Date(ms).toISOString() : null;
}