Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
35.0 KB
Raw Blame
/**
 * Retrieval Reflex — resolver core (issue #1981, Layer 1).
 *
 * Given salient candidate surface-forms (from entity-salience.ts) and a real
 * BrainEngine, resolve the ones that map to an EXISTING brain page and return a
 * compact POINTER block (name → slug → safe one-line synopsis) to inject into
 * the system prompt. Detect + point, NEVER auto-dump the body — the agent makes
 * the deliberate get_page call when the entity is actually the subject.
 *
 * This is the NARROW operation behind the resolve capability: it takes
 * candidates and returns pointers. The IPC (serve) and host (ctx.brainQuery)
 * paths run THIS SAME function server-side so no raw SQL ever crosses a trust
 * boundary — the wire only carries candidates in and pointers out.
 *
 * Deterministic, zero-LLM. Precision-biased resolution (no trgm-fuzzy):
 *   1. alias-first  — page_aliases exact (unambiguous single-slug only)
 *   2. title + slug-suffix — lower(title) exact OR slug suffix match
 *      (real slugs are namespaced people/alice-example; bare slugify misses).
 *
 * Privacy (eng-review D5): the synopsis is taken from a SAFE source —
 * frontmatter `summary` if present, else the page body with takes/private-fact
 * fences STRIPPED (same boundary get_page applies to untrusted readers). Raw
 * compiled_truth is never injected. Page visibility: `visibility: private`
 * and derived-private pages never resolve unless the caller passes
 * `excludePrivate: false` (trusted local only) — the same page filter remote
 * search applies (search/private-visibility.ts).
 */

import type { BrainEngine } from '../engine.ts';
import type { TrustTier } from '../trust/tier.ts';
import type { ReadEligibility } from '../eligibility/policy.ts';
import { proactiveEligibility } from '../eligibility/registry.ts';
import { pageActivationVerdicts, pageKey } from '../eligibility/activation.ts';
import { renderTrustedInline, trustFields, type TrustFields } from '../eligibility/labels.ts';
import { normalizeAlias } from '../search/alias-normalize.ts';
import { CJK_SLUG_CHARS } from '../cjk.ts';
import { escapeLikePattern } from '../search/sql-ranking.ts';
import { slugify } from '../entities/resolve.ts';
import { stripTakesFence } from '../takes-fence.ts';
import { stripFactsFence } from '../facts-fence.ts';
import { redactFindings } from '../secret-scan.ts';
import { privatePagesFilterForCaller, remoteReadFloorSql } from '../search/private-visibility.ts';
import type { EntityCandidate } from './entity-salience.ts';
import { reflexPointerRationale } from './reflex-rationale.ts';
import { preferEntityTitleMatches } from './title-matches.ts';
import { logVolunteerEventsFireAndForget, volunteerEventRowsFrom } from './volunteer-events.ts';
import { boundedProjectedPrefix } from '../page-window/document.ts';
import { boundedBodyPrefixSql, boundedRawPrefix, overlaidBoundedRows } from '../page-window/bounded-lead.ts';

/** Large pages: candidate rows carry a bounded body prefix (the synopsis reads only its first sentence). */
const PREFIX_SQL = boundedBodyPrefixSql('p');

export { reflexPointerRationale } from './reflex-rationale.ts';

/** Default cap on pointers injected per turn (config: retrieval_reflex_max_pointers). */
export const DEFAULT_MAX_POINTERS = 3;
const SYNOPSIS_MAX = 160;

// #3746 — pure-CJK norm (every char in the shared Han/kana/hangul ranges).
// These norms get the extra exact-title/exact-slug arm: CJK candidates are
// n-grams with no capitalization signal, `slugify()` strips CJK entirely (so
// the generic slug arm can never fire for them), and the alias table alone
// covers only explicitly registered aliases.
const PURE_CJK_RE = new RegExp(`^[${CJK_SLUG_CHARS}]+$`, 'u');

/** Which resolution arm produced a pointer (provenance → honest confidence). */
/** `recall`: a System One S6 keyword-only retrieval fired by the know-to-ask slot (never produced by the resolver). */
/**
 * #6195 arm 2.6 ('weak-title'): a lowercase 2-3-word weak n-gram may match the
 * exact title of an entity page (person, company, organization) when that
 * title is globally unique across the considered sources and no other arm
 * resolved the n-gram. Concepts and other types are excluded: their titles are
 * common phrases ("open source"). Fail-open: the alias arm already ran.
 */
async function weakTitleHits(engine: BrainEngine, sourceIds: string[], privacySql: string, norms: string[]): Promise<PageRow[]> {
  if (!norms.length) return [];
  try {
    const rows = await engine.executeRaw<PageRow>(
      `SELECT p.slug, p.source_id, p.title, p.type, p.frontmatter, ${PREFIX_SQL} AS compiled_truth
         FROM pages p
        WHERE p.deleted_at IS NULL ${privacySql}
          AND p.source_id = ANY($1::text[])
          AND lower(p.title) = ANY($2::text[])`,
      [sourceIds, norms],
    );
    const byTitle = new Map<string, PageRow[]>();
    for (const r of rows) byTitle.set((r.title ?? '').toLowerCase(), [...(byTitle.get((r.title ?? '').toLowerCase()) ?? []), r]);
    return [...byTitle.values()].filter((list) => list.length === 1 && WEAK_TITLE_ENTITY_TYPES.has(String(list[0].type))).map((list) => list[0]);
  } catch {
    return [];
  }
}

/** #6195: page types whose exact title a lowercase multi-word n-gram may match. */
const WEAK_TITLE_ENTITY_TYPES = new Set(['person', 'company', 'organization']);

export type ResolveArm = 'alias' | 'title' | 'slug-suffix' | 'title-surname' | 'cjk-title' | 'weak-title' | 'recall';

/**
 * v0.43 (#2095) — arm → confidence. Lives HERE, next to the arm definitions,
 * so arm identity and its score can't drift apart (eng-review note). The
 * volunteer layer imports these; small deterministic boosts (multi-turn /
 * newest-turn mention) are added on top there.
 *
 * 'title-surname' (v0.46.15 identity wave) sits at 0.72 — deliberately ABOVE
 * the volunteer layer's 0.70 default gate (a 0.6x score would be silently
 * discarded there) and below 'title' (an exact-title hit is stronger
 * evidence than a surname-tail match).
 *
 * 'cjk-title' (#3746) also sits at 0.72: a pure-CJK weak n-gram that exactly
 * matches a unique page title/slug. Exact evidence, but the gram lacks the
 * capitalization signal a strong 'title' candidate carries — score it with
 * the surname class, above the volunteer gate.
 */
export const ARM_CONFIDENCE: Record<ResolveArm, number> = {
  alias: 0.9,
  title: 0.8,
  'title-surname': 0.72,
  'cjk-title': 0.72,
  'weak-title': 0.72,
  'slug-suffix': 0.6,
  recall: 0.5,
};

export interface ReflexPointer {
  display: string;
  slug: string;
  /** Which brain source the page lives in (federated callers need it for dedup). */
  source_id: string;
  synopsis: string;
  /** Resolution provenance (v0.43 #2095). */
  arm: ResolveArm;
  /** Base arm confidence (ARM_CONFIDENCE[arm]); callers may boost. */
  confidence: number;
  /**
   * normalizeAlias form of the CANDIDATE that resolved this pointer (v0.43
   * #2095) — lets the volunteer layer join pointers back to window-salience
   * metadata without guessing from the display label (which falls back to the
   * page title when the candidate surface differs, e.g. alias "Swami" →
   * title "Swami X"). Absent only when suffix classification couldn't
   * recover the source candidate.
   */
  matchedNorm?: string;
  /** #5575 A6: the page's trust tier and short write origin (rendered as a compact label). */
  trust_tier?: TrustTier;
  origin?: string;
  /** #5575 CEO-20: the page carries an unconfirmed instruction-family flag (kept under `trust.agent_activation=allow`). */
  unconfirmed?: true;
}

export interface PointerBlock {
  pointers: ReflexPointer[];
  /** Pre-rendered markdown for systemPromptAddition. */
  text: string;
}

export interface ResolvePointersOpts {
  maxPointers?: number;
  /**
   * Joined text of PRIOR turns + already-loaded page bodies (NOT the current
   * user message). Pointers whose slug/title already appear here are suppressed
   * — the agent has seen them. MUST exclude the current turn, or the triggering
   * message's own mention would suppress every pointer (eng-review/Codex fix).
   */
  priorContextText?: string;
  /**
   * v0.43 (#2095, codex D7) — suppression mode.
   *   'slug-and-title' (default, window=1 legacy): suppress when the slug OR
   *     the page title appears whole-word in prior context.
   *   'slug-only' (REQUIRED under multi-turn windowing): suppress on slug
   *     presence only. Slugs only enter context when a pointer block or page
   *     body was actually injected; a bare mention of "Alice Example" in a
   *     prior turn never contains `people/alice-example`. The title rule
   *     would suppress every entity merely MENTIONED in a prior window turn
   *     — breaking window extraction by construction.
   */
  suppression?: 'slug-and-title' | 'slug-only';
  /**
   * v0.43 (#2095) — federated scope: resolve across these sources instead of
   * the single positional sourceId. Precedence mirrors sourceScopeOpts
   * (federated array > scalar). Alias arm loops per source; the title/slug
   * arm uses source_id = ANY(...) in one query.
   */
  sourceIds?: string[];
  /**
   * v0.46.15 identity wave — kill switch for the two new lexical arms (the
   * weak-candidate alias arm and the surname arm). Default ON (undefined =
   * enabled); `false` reproduces pre-wave resolution exactly. Threaded from
   * the file-plane config `retrieval_reflex_lexical_arms` / env
   * `GBRAIN_RETRIEVAL_REFLEX_LEXICAL_ARMS` by callers that own a loaded
   * config — the resolver itself never touches config (sync hot path).
   */
  lexicalArms?: boolean;
  /**
   * Hide `visibility: private` (and derived-private) pages from every arm,
   * using the same predicate remote search applies. Default true
   * (fail-closed): pointers are injected into agent prompts, so the IPC
   * resolve, turn-context and direct-Postgres reflex lanes stay world-only.
   * Only a trusted local caller (volunteer_context with remote === false,
   * via resolveExcludePrivatePages) passes false.
   */
  excludePrivate?: boolean;
  /** A remote read: `excludePrivate` applies the caller's policy instead of the plain privacy fragment. */
  forCaller?: boolean;
  /**
   * #5575 (CEO-20, ENG-8): the proactive eligibility the enclosing surface
   * resolved (read floor plus activation control). Absent: the resolver
   * applies the `retrieval_reflex` surface policy itself (fail-closed).
   */
  eligibility?: ReadEligibility;
  /** #5575 DX-10: receives the page keys (`source_id:slug`) of deliverable pointers activation control withheld. */
  onWithheld?: (keys: string[]) => void;
}

export interface PageRow {
  slug: string;
  source_id: string;
  title: string;
  type: string | null;
  frontmatter: Record<string, unknown> | null;
  compiled_truth: string | null;
}

/**
 * Resolve candidates to a pointer block. Returns null when nothing resolves
 * (so the caller injects nothing). Never throws for data reasons — each arm is
 * independently guarded so a pre-v110 brain (no page_aliases) still gets the
 * title/slug arm.
 */
export async function resolveEntitiesToPointers(
  engine: BrainEngine,
  sourceId: string,
  candidates: EntityCandidate[],
  opts: ResolvePointersOpts = {},
): Promise<PointerBlock | null> {
  if (!candidates.length) return null;
  const maxPointers = opts.maxPointers ?? DEFAULT_MAX_POINTERS;
  const priorLc = (opts.priorContextText ?? '').toLowerCase();

  // v0.46.15: weak-alias + surname arms share one kill switch (default ON).
  const lexicalArms = opts.lexicalArms !== false;
  const privacySql = opts.excludePrivate === false ? '' : `AND ${opts.forCaller ? privatePagesFilterForCaller('p') : remoteReadFloorSql('p')}`;

  // display lookup keyed by normalized query, so resolved slugs can recover a
  // human surface form for the pointer label.
  const displayByNorm = new Map<string, string>();
  const aliasNorms: string[] = [];
  const titlesLc: string[] = [];
  const exactSlugs: string[] = [];
  const slugSuffixes: string[] = [];
  // Weak candidates resolve through the ALIAS arm only (exact, unique). Their
  // norms are tracked so the alias fold can apply the stricter cross-source
  // uniqueness rule to them.
  const weakNorms = new Set<string>();
  const weakTitleNorms = new Set<string>(); // #6195: multi-word weak n-grams, also probed against exact entity titles (arm 2.6)
  // Surname arm inputs: strong single-token capitalized candidates ≥3 chars.
  const surnamePatterns: string[] = [];
  const surnameTokens: string[] = []; // lower(token), parallel to patterns
  const surnameTokenToNorm = new Map<string, string>();
  // Reverse maps for arm-2 provenance (which candidate produced a row) —
  // populated in this same pass so the derivations happen exactly once.
  const titleToNorm = new Map<string, string>();
  const slugToNorm = new Map<string, string>();
  for (const c of candidates) {
    // Lowercase WEAK candidates (entity-salience step 2.5) may probe the
    // alias table ONLY — never the title/slug/suffix arms, where ordinary
    // lowercase words would fabricate pointers. Gated by the kill switch.
    if (c.weak) {
      if (!lexicalArms) continue;
      const wnorm = normalizeAlias(c.query);
      if (!wnorm) continue;
      if (!displayByNorm.has(wnorm)) displayByNorm.set(wnorm, c.display);
      if (c.multiToken) weakTitleNorms.add(wnorm);
      if (!weakNorms.has(wnorm)) {
        weakNorms.add(wnorm);
        aliasNorms.push(wnorm);
      }
      continue;
    }
    const norm = normalizeAlias(c.query);
    if (!norm) continue;
    if (!displayByNorm.has(norm)) displayByNorm.set(norm, c.display);
    aliasNorms.push(norm);
    const tl = c.query.toLowerCase();
    titlesLc.push(tl);
    if (!titleToNorm.has(tl)) titleToNorm.set(tl, norm);
    const s = slugify(c.query);
    if (s) {
      exactSlugs.push(s);
      slugSuffixes.push(`%/${s}`);
      if (!slugToNorm.has(s)) slugToNorm.set(s, norm);
    }
    // Surname arm (v0.46.15, kta-pos variant 4): a strong single capitalized
    // token ≥3 chars may be a surname-only reference ("Did Galewright ever…").
    // Escaped for LIKE (backslash is Postgres' default escape char — no
    // ESCAPE clause, which the `LIKE ANY(array)` form doesn't accept).
    if (lexicalArms && !/\s/.test(c.query) && c.query.length >= 3 && /^\p{Lu}/u.test(c.query)) {
      const tokenLc = c.query.toLowerCase();
      if (!surnameTokenToNorm.has(tokenLc)) {
        surnameTokenToNorm.set(tokenLc, norm);
        surnameTokens.push(tokenLc);
        surnamePatterns.push(`% ${escapeLikePattern(tokenLc)}`);
      }
    }
  }
  if (!aliasNorms.length) return null;

  // Federated scope (v0.43 #2095): explicit sourceIds win over the scalar.
  const sourceIds = opts.sourceIds?.length ? opts.sourceIds : [sourceId];

  // Ordered set of resolved (source, slug) pairs with arm provenance —
  // alias hits pushed first → higher confidence.
  const resolved: Array<{ slug: string; source_id: string; arm: ResolveArm; matchedNorm?: string }> = [];
  const seen = new Set<string>();
  // Neither source ids nor slugs contain spaces, so a space separator is safe.
  const keyOf = (src: string, slug: string) => `${src} ${slug}`;
  const push = (slug: string, src: string, arm: ResolveArm, matchedNorm?: string) => {
    if (!slug) return;
    const k = keyOf(src, slug);
    if (!seen.has(k)) {
      seen.add(k);
      resolved.push({ slug, source_id: src, arm, matchedNorm });
    }
  };
  // Arm 1 — alias-first. Unambiguous single-slug hits only, per source (no
  // engine-interface change for federation). Guarded: pre-v110 brains throw
  // "relation page_aliases does not exist" — swallow and continue.
  // Per-source lookups are independent — run them concurrently so a
  // federated caller (M granted sources) pays one RTT, not M sequential
  // ones (~71ms each cross-region; the reflex runs under a 1.5s budget).
  // Results are folded back in sourceIds order so pointer ordering stays
  // deterministic. Per-source failures degrade independently (pre-v110
  // brains have no page_aliases table).
  const aliasResults = await Promise.allSettled(
    sourceIds.map((src) => engine.resolveAliases(aliasNorms, { sourceId: src })),
  );
  const anyAliasSourceFailed = aliasResults.some((r) => r.status !== 'fulfilled');
  // Liveness BEFORE uniqueness: page_aliases has no FK, so a norm's hit list
  // can carry rows for deleted/renamed pages. Deciding uniqueness on raw hits
  // lets a stale row veto the sole live target (hits.length becomes 2), or
  // conversely leaves a phantom looking unique. One batched live-check over
  // every hit slug; result rows carry their true (source_id, slug) so the
  // ANY(sources) × ANY(slugs) over-match cannot mis-key. If the check itself
  // fails, strong arms fall back to raw-hit uniqueness (phantom pointers are
  // still dropped by the downstream hydration) and the weak fold goes
  // fail-closed.
  const liveAliasKeys = new Set<string>();
  let liveCheckOk = false;
  {
    const hitSlugs = new Set<string>();
    for (const r of aliasResults) {
      if (r.status !== 'fulfilled') continue;
      for (const hits of r.value.values()) for (const h of hits) hitSlugs.add(h.slug);
    }
    if (hitSlugs.size) {
      try {
        const liveRows = await engine.executeRaw<{ slug: string; source_id: string }>(
          `SELECT p.slug, p.source_id FROM pages p
            WHERE p.deleted_at IS NULL AND p.source_id = ANY($1::text[]) AND p.slug = ANY($2::text[]) ${privacySql}`,
          [sourceIds, [...hitSlugs]],
        );
        for (const r of liveRows) liveAliasKeys.add(keyOf(r.source_id, r.slug));
        liveCheckOk = true;
      } catch {
        /* fall back below */
      }
    } else {
      liveCheckOk = true;
    }
  }
  const liveHitsFor = (
    r: PromiseSettledResult<Map<string, Array<{ slug: string; source_id: string }>>>,
    src: string,
    norm: string,
  ): Array<{ slug: string; source_id: string }> => {
    if (r.status !== 'fulfilled') return [];
    const hits = r.value.get(norm) ?? [];
    return liveCheckOk ? hits.filter((h) => liveAliasKeys.has(keyOf(h.source_id || src, h.slug))) : hits;
  };
  for (let i = 0; i < sourceIds.length; i++) {
    for (const norm of aliasNorms) {
      if (weakNorms.has(norm)) continue; // weak norms fold below (stricter rule)
      const hits = liveHitsFor(aliasResults[i], sourceIds[i], norm);
      if (hits.length === 1) push(hits[0].slug, sourceIds[i], 'alias', norm);
    }
  }
  // Weak norms: GLOBAL uniqueness across all considered sources (v0.46.15,
  // stricter than the strong per-source rule) — a lowercase word that is a
  // registered alias in two sources injects nothing. FAIL-CLOSED on partial
  // visibility (adversarial F2): if any source's alias lookup failed, or the
  // live-check did, uniqueness cannot be decided globally — a transient DB
  // blip must not make an ambiguous alias look unique. Skip the fold; the
  // next turn retries with full visibility.
  if (weakNorms.size && !anyAliasSourceFailed && liveCheckOk) {
    for (const norm of weakNorms) {
      const all: Array<{ slug: string; source_id: string }> = [];
      for (let i = 0; i < sourceIds.length; i++) {
        for (const h of liveHitsFor(aliasResults[i], sourceIds[i], norm)) {
          all.push({ slug: h.slug, source_id: sourceIds[i] });
        }
      }
      if (all.length === 1) push(all[0].slug, all[0].source_id, 'alias', norm);
    }
  }

  // Arm 2 — exact title OR slug-suffix. This is the recall fix: a bare "Alice
  // Example" slugifies to alice-example, but the real page is people/alice-example,
  // so a plain slug = ANY() misses. Match lower(title) exactly or the slug suffix.
  let rows: PageRow[] = [];
  const useSurnameArm = surnamePatterns.length > 0;
  try {
    // The surname predicate rides the SAME query when armed: person pages
    // whose lower(title) ends with " <token>". Patterns are pre-escaped for
    // LIKE (backslash default escape); type='person' kills the company-tail
    // class ("Labs", "Systems" as pseudo-surnames).
    rows = useSurnameArm
      ? await engine.executeRaw<PageRow>(
          `SELECT p.slug, p.source_id, p.title, p.type, p.frontmatter, ${PREFIX_SQL} AS compiled_truth
             FROM pages p
            WHERE p.deleted_at IS NULL ${privacySql}
              AND p.source_id = ANY($1::text[])
              AND ( lower(p.title) = ANY($2::text[])
                 OR p.slug = ANY($3::text[])
                 OR p.slug LIKE ANY($4::text[])
                 OR (lower(p.title) LIKE ANY($5::text[]) AND p.type = 'person') ) ORDER BY p.id`,
          [sourceIds, titlesLc, exactSlugs, slugSuffixes, surnamePatterns],
        )
      : await engine.executeRaw<PageRow>(
          `SELECT p.slug, p.source_id, p.title, p.type, p.frontmatter, ${PREFIX_SQL} AS compiled_truth
             FROM pages p
            WHERE p.deleted_at IS NULL ${privacySql}
              AND p.source_id = ANY($1::text[])
              AND ( lower(p.title) = ANY($2::text[])
             OR p.slug = ANY($3::text[])
             OR p.slug LIKE ANY($4::text[]) ) ORDER BY p.id`,
          [sourceIds, titlesLc, exactSlugs, slugSuffixes],
        );
  } catch {
    rows = [];
  }
  // Hydrate alias-resolved pages too (their bodies for the synopsis) if not in rows.
  const rowByKey = new Map<string, PageRow>();
  for (const r of rows) rowByKey.set(keyOf(r.source_id, r.slug), r);
  const aliasOnly = resolved.filter((p) => !rowByKey.has(keyOf(p.source_id, p.slug)));
  if (aliasOnly.length) {
    try {
      const extra = await engine.executeRaw<PageRow>(
        `SELECT p.slug, p.source_id, p.title, p.type, p.frontmatter, ${PREFIX_SQL} AS compiled_truth
           FROM pages p
          WHERE p.deleted_at IS NULL ${privacySql} AND p.source_id = ANY($1::text[]) AND p.slug = ANY($2::text[])`,
        [sourceIds, aliasOnly.map((p) => p.slug)],
      );
      for (const r of extra) rowByKey.set(keyOf(r.source_id, r.slug), r);
    } catch {
      /* ignore — alias slug may be stale */
    }
  }
  // Title/slug matches that weren't alias hits, appended after alias hits.
  // Arm provenance per row is classified in JS (codex D8) — the combined OR
  // can't report which predicate matched. Classification is per-(row,
  // matching-set) with exact-arm precedence (eng review): a row can
  // title-match candidate X AND surname-match candidate Y — the exact hit
  // wins. Rows matched by NO exact set fall through to the surname check.
  const titleSet = new Set(titlesLc);
  // token → surname-matched rows; pushed only when the token is UNAMBIGUOUS
  // (exactly one page across the considered sources — mirror of the alias
  // arm's posture; an ambiguous surname injects nothing).
  //
  // Ambiguity is counted over ALL person rows carrying the surname,
  // INDEPENDENT of which arm claims a row (adversarial F1): classification
  // precedence (title/slug win) would otherwise remove a title-claimed
  // namesake from the surname count — with "Jane Galewright" resolved by
  // title and a bare "Galewright" in the same window, the OTHER Galewright
  // would look unique and inject the wrong person. The SQL OR fetches every
  // surname-matching person row regardless of later classification, so this
  // coverage count is complete.
  const surnameCoverage = new Map<string, number>();
  if (useSurnameArm) {
    for (const r of rows) {
      if (r.type !== 'person') continue;
      const titleLc = (r.title ?? '').toLowerCase();
      const token = surnameTokens.find((t) => titleLc.endsWith(` ${t}`));
      if (token) surnameCoverage.set(token, (surnameCoverage.get(token) ?? 0) + 1);
    }
  }
  const surnameHits = new Map<string, Array<{ slug: string; source_id: string }>>();
  for (const r of rows) {
    const titleLc = (r.title ?? '').toLowerCase();
    if (titleSet.has(titleLc)) {
      push(r.slug, r.source_id, 'title', titleToNorm.get(titleLc));
      continue;
    }
    // Slug arm: exact slugified-candidate match, else suffix scan.
    const tail = r.slug.includes('/') ? r.slug.slice(r.slug.lastIndexOf('/') + 1) : r.slug;
    const slugNorm = slugToNorm.get(r.slug) ?? slugToNorm.get(tail);
    if (slugNorm !== undefined) {
      push(r.slug, r.source_id, 'slug-suffix', slugNorm);
      continue;
    }
    // Surname arm (v0.46.15): this row got in via the surname predicate only.
    if (useSurnameArm && r.type === 'person') {
      const token = surnameTokens.find((t) => titleLc.endsWith(` ${t}`));
      if (token) {
        const list = surnameHits.get(token) ?? [];
        list.push({ slug: r.slug, source_id: r.source_id });
        surnameHits.set(token, list);
      }
    }
  }
  for (const [token, hits] of surnameHits) {
    // hits counts rows the surname arm alone claimed; coverage counts every
    // holder including title/slug-claimed namesakes. Both must be 1.
    if (hits.length === 1 && (surnameCoverage.get(token) ?? 0) === 1) {
      push(hits[0].slug, hits[0].source_id, 'title-surname', surnameTokenToNorm.get(token));
    }
  }

  // Arm 2.5 — pure-CJK weak exact-title/exact-slug (#3746, 'cjk-title').
  // CJK weak n-grams may probe EXACT title/slug equality on top of the alias
  // arm: slugify() strips CJK so the generic slug arm can never fire, and CJK
  // pages routinely have no registered alias. Never suffix/surname (an n-gram
  // tail-matching slugs would over-match wildly). Gated by the same
  // lexicalArms kill switch as the other weak arms; GLOBAL uniqueness across
  // the considered sources (mirror of the weak-alias fold) — an ambiguous
  // gram injects nothing.
  if (lexicalArms && weakNorms.size) {
    const armResolvedNorms = new Set(resolved.map((r) => r.matchedNorm).filter(Boolean));
    const cjkNorms = [...weakNorms].filter((n) => PURE_CJK_RE.test(n) && !armResolvedNorms.has(n));
    if (cjkNorms.length) {
      try {
        const cjkRows = await engine.executeRaw<PageRow>(
          `SELECT p.slug, p.source_id, p.title, p.type, p.frontmatter, ${PREFIX_SQL} AS compiled_truth
             FROM pages p
            WHERE p.deleted_at IS NULL ${privacySql}
              AND p.source_id = ANY($1::text[])
              AND ( lower(p.title) = ANY($2::text[]) OR p.slug = ANY($3::text[]) )`,
          [sourceIds, cjkNorms, cjkNorms],
        );
        const cjkHits = new Map<string, Array<{ slug: string; source_id: string }>>();
        for (const r of cjkRows) {
          rowByKey.set(keyOf(r.source_id, r.slug), r); // hydrate for synopsis
          const titleLc = (r.title ?? '').toLowerCase();
          for (const n of cjkNorms) {
            if (titleLc === n || r.slug === n) {
              const list = cjkHits.get(n) ?? [];
              list.push({ slug: r.slug, source_id: r.source_id });
              cjkHits.set(n, list);
            }
          }
        }
        for (const [n, hits] of cjkHits) {
          if (hits.length === 1) push(hits[0].slug, hits[0].source_id, 'cjk-title', n);
        }
      } catch {
        /* fail-open — the alias arm already ran */
      }
    }
  }

  // Arm 2.6 — lowercase multi-word weak exact-title (#6195; see weakTitleHits).
  if (lexicalArms && weakTitleNorms.size) for (const r of await weakTitleHits(engine, sourceIds, privacySql, [...weakTitleNorms].filter((n) => !resolved.some((x) => x.matchedNorm === n)))) {
    rowByKey.set(keyOf(r.source_id, r.slug), r); push(r.slug, r.source_id, 'weak-title', (r.title ?? '').toLowerCase());
  }

  const trust = await gatePointerCandidates(engine, resolved, opts); // #5575 gate; then pointers by confidence, suppression + cap
  const suppression = opts.suppression ?? 'slug-and-title';
  const pointers: ReflexPointer[] = [];
  for (const { slug, source_id, arm, matchedNorm } of await preferEntityTitleMatches(engine, resolved, m => rowByKey.get(keyOf(m.source_id, m.slug)), m => trust.has(pageKey(m)), slugToNorm)) {
    const row = rowByKey.get(keyOf(source_id, slug));
    if (!row || !trust.has(pageKey({ source_id, slug }))) continue;
    // Suppression: already present in PRIOR context. The current turn is
    // deliberately excluded from priorContextText. Under windowing
    // ('slug-only', codex D7) only the slug counts — a slug appears in prior
    // context only when a pointer/page was actually surfaced there, while a
    // title appears on any bare mention.
    if (priorLc) {
      if (priorLc.includes(slug.toLowerCase())) continue;
      if (suppression === 'slug-and-title') {
        const titleLc = (row.title ?? '').toLowerCase();
        if (titleLc && wholeWordIncludes(priorLc, titleLc)) continue;
      }
    }
    const display = displayForRow(row, displayByNorm);
    const synopsis = safeSynopsis((await overlaidBoundedRows(engine, [row]))[0]!);
    pointers.push({ display, slug, source_id, synopsis, arm, confidence: ARM_CONFIDENCE[arm], matchedNorm, ...trust.get(pageKey({ source_id, slug })) });
    if (pointers.length >= maxPointers) break;
  }

  if (!pointers.length) return null;
  return { pointers, text: renderPointerBlock(pointers) };
}

/**
 * #5575 (CEO-20, A6): one query over every resolved candidate page. Returns
 * the label fields of the pages a pointer may name; pages below the floor or
 * unreadable are absent (fail-closed), and activation-suppressed pages are
 * absent and reported through `opts.onWithheld`.
 */
async function gatePointerCandidates(engine: BrainEngine, resolved: ReadonlyArray<{ source_id: string; slug: string }>,
  opts: ResolvePointersOpts): Promise<Map<string, TrustFields>> {
  const policy = opts.eligibility ?? await proactiveEligibility({ engine }, 'retrieval_reflex');
  const verdicts = await pageActivationVerdicts(engine, resolved.map(r => ({ source_id: r.source_id, slug: r.slug })), policy).catch(() => null);
  const out = new Map<string, TrustFields>();
  const withheld: string[] = [];
  for (const [key, v] of verdicts ?? []) {
    if (v.belowFloor) continue;
    if (v.suppressed) withheld.push(key.replace('\u0000', ':'));
    else out.set(key, { ...trustFields(v.tier, v.origin), ...(v.unconfirmed ? { unconfirmed: true as const } : {}) });
  }
  if (withheld.length) opts.onWithheld?.(withheld);
  return out;
}

/** Recover a display label: prefer the matched candidate surface, else the page title. */
function displayForRow(row: PageRow, displayByNorm: Map<string, string>): string {
  const byTitle = displayByNorm.get(normalizeAlias(row.title ?? ''));
  if (byTitle) return byTitle;
  // try the slug tail (people/alice-example → alice-example)
  const tail = row.slug.includes('/') ? row.slug.slice(row.slug.lastIndexOf('/') + 1) : row.slug;
  return row.title || tail;
}

/**
 * Privacy-safe synopsis (eng-review D5). Prefer a curated frontmatter `summary`;
 * otherwise strip takes/private-fact fences from the body (the same boundary
 * get_page applies to untrusted readers) and take the first sentence. Never
 * returns raw compiled_truth.
 *
 * Exported for the MEMORY_VERBS v1 entity card (verbs/entity-card.ts) — the
 * card's `summary` field runs through THIS boundary, not a parallel one.
 * Also consumed by compile-view.ts (cathedral-5), which widens `maxLen` to
 * 600 for compiled-context excerpts; the default stays SYNOPSIS_MAX.
 */
export function safeSynopsis(
  row: PageRow,
  opts: { keepVisibility?: ('private' | 'world')[]; maxLen?: number } = {},
): string {
  // v0.45.7 ambient recall: world-only by default (the injected-context posture).
  // The ONLY widening caller is the entity-card builder for a trusted-local
  // include_private pack (entity-card.ts) — the pointer/volunteer arms always
  // run world-only (turn mode never widens).
  const keepVisibility = opts.keepVisibility ?? ['world'];
  const maxLen = opts.maxLen ?? SYNOPSIS_MAX;
  // Redact the whole source field before collapse/clip: a cut or
  // space-joined credential no longer matches the scanner.
  const fmSummary = row.frontmatter?.summary;
  if (typeof fmSummary === 'string' && fmSummary.trim()) {
    return clip(collapse(redactFindings(fmSummary, { highEntropy: true }).text), maxLen);
  }
  // Large pages: only a bounded prefix is sanitized. World-only reads take
  // the sanitized projection's prefix; a trusted widening keeps private rows
  // through the strip below, which drops a fence the cut leaves open.
  const body = keepVisibility.length === 1 && keepVisibility[0] === 'world'
    ? boundedProjectedPrefix(row.compiled_truth) : boundedRawPrefix(row.compiled_truth);
  if (!body) return '';
  const stripped = redactFindings(stripFactsFence(stripTakesFence(body), { keepVisibility }), { highEntropy: true }).text;
  // Drop frontmatter block, markdown headings, and blank lines; first real prose line.
  const firstProse = stripped
    .replace(/^---[\s\S]*?---\s*/m, '')
    .split('\n')
    .map((l) => l.trim())
    .find((l) => l && !l.startsWith('#') && !l.startsWith('<!--'));
  if (!firstProse) return '';
  // first sentence-ish
  const sentence = firstProse.split(/(?<=[.!?])\s/)[0];
  return clip(collapse(sentence), maxLen);
}

function collapse(s: string): string {
  return s.replace(/\s+/g, ' ').trim();
}
function clip(s: string, n: number): string {
  return s.length > n ? s.slice(0, n - 1).trimEnd() + '…' : s;
}

/** Whole-word containment so "ab" doesn't match inside "fabric". */
function wholeWordIncludes(haystack: string, needle: string): boolean {
  if (!needle) return false;
  const esc = needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
  return new RegExp(`(^|\\W)${esc}(\\W|$)`).test(haystack);
}

export function renderPointerBlock(pointers: ReflexPointer[]): string {
  const lines = [
    '## Brain pages mentioned this turn',
    'You referenced entities with existing brain pages. Open the page before relying on',
    'details — do not answer from memory.',
    '',
  ];
  for (const p of pointers) lines.push(renderPointerLine(p));
  return lines.join('\n');
}

/**
 * One pointer list item. #5575 A6: a labeled pointer carries its compact
 * trust label before the synopsis (an external page's synopsis is wrapped
 * inline as data); an unlabeled one renders as before.
 */
export function renderPointerLine(p: Pick<ReflexPointer, 'display' | 'slug' | 'synopsis' | 'trust_tier' | 'origin' | 'unconfirmed'>): string {
  const trusted = p.trust_tier ? ` ${renderTrustedInline(p.synopsis, { trust_tier: p.trust_tier, origin: p.origin ?? 'legacy', ...(p.unconfirmed ? { unconfirmed: true as const } : {}) })}` : '';
  const syn = p.trust_tier ? (trusted ? ` —${trusted}` : '') : p.synopsis ? ` — ${p.synopsis}` : '';
  return `- **${p.display}** → \`${p.slug}\`${syn} (use get_page before relying on details)`;
}

/**
 * v0.43 (#2095, codex D11 + red-team) — ambient-channel feedback logging,
 * ACCEPT-SIDE ONLY. Called by the delivery points (the serve IPC server after
 * a successful write; the direct-Postgres reflex rung after its per-turn
 * timeout admitted the block) — never inside the resolver itself, because a
 * pointer block that timed out client-side was NEVER injected into a prompt,
 * and logging it would inflate "volunteered" counts and drag the measured
 * precision toward zero (corrupting the exact stats users tune
 * min_confidence with).
 */
export function logDeliveredReflexPointers(engine: BrainEngine, pointers: ReflexPointer[]): void {
  if (!pointers.length) return;
  // Register work synchronously. A dynamic import here creates a late-
  // registration race: callers can drain the sink before the import resolves.
  try {
    logVolunteerEventsFireAndForget(
      engine,
      volunteerEventRowsFrom(
        pointers.map((p) => ({ ...p, rationale: reflexPointerRationale(p) })),
        { channel: 'reflex' },
      ),
    );
  } catch {
    /* telemetry only */
  }
}