Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
36.9 KB
Raw Blame
/**
 * v0.29.1 — merged query-intent classifier.
 *
 * Replaces v0.29.0's `intent.ts` (which only emitted a detail suggestion).
 * After D1 + D4 the codebase needs ONE classifier that returns three
 * suggestions from a single regex pass:
 *
 *   - intent:           original v0.29.0 type ('entity' | 'temporal' | 'event' | 'general')
 *   - suggestedDetail:  v0.29.0 mapping (entity→low, temporal/event→high)
 *   - suggestedSalience: NEW for v0.29.1 — 'off' | 'on' | 'strong'
 *   - suggestedRecency:  NEW for v0.29.1 — 'off' | 'on' | 'strong'
 *
 * Salience and recency are TRULY ORTHOGONAL (per D9):
 *   - salience boosts pages with high emotional_weight + take_count (mattering)
 *   - recency boosts pages with recent effective_date (per-prefix decay)
 * Both can fire, neither can fire, or just one.
 *
 * The classifier follows "current state → on. canonical truth → off." with
 * a NARROW exception per D6: explicit temporal bounds (today / this week /
 * right now / since X / last N days) override canonical-pattern wins. So
 * "who is X right now" → suggestedRecency='on' even though "who is" is a
 * canonical pattern.
 *
 * Pure module. No DB, no LLM, no async — with ONE seam: the shipped banks
 * are English-only regex, so a brain queried in another language never fired
 * the recency/salience stages at all (#4415). `applyIntentPatternConfig`
 * merges per-brain pattern extensions (the `search.intent_patterns` config
 * key, same operator-extension shape as `emotional_weight.high_tags`) over
 * the shipped banks; `classifyQueryWithBrainPatterns` is the async
 * config-loading wrapper hybridSearch calls. classifyQuery itself stays
 * sync + deterministic for a given applied config.
 *
 * wave-g: the config-backed extensions are cached PER ENGINE (WeakMap +
 * short TTL — no config-write invalidation seam exists), so hybridSearch's
 * hot path pays one engine.getConfig round-trip per TTL window instead of
 * one per call, and a multi-engine process (migrate source+target, tests)
 * can't apply one brain's patterns to another brain's queries. The
 * process-global `applyIntentPatternConfig` seam remains for sync callers
 * and tests. `loadEngineIntentPatterns` also exposes a fingerprint of the
 * applied config for the query-cache knobs hash (a pattern-config change
 * changes classification → results, so it must key cache rows).
 * Tested in test/query-intent.test.ts + test/query-intent-config.test.ts.
 */

import { createHash } from 'node:crypto';

export type QueryIntent = 'entity' | 'temporal' | 'event' | 'concept' | 'general';

export type SalienceMode = 'off' | 'on' | 'strong';
export type RecencyMode = 'off' | 'on' | 'strong';

/**
 * v0.36 cross-modal wave: modality axis (D6).
 *
 * - 'text' (default): existing text-embedding path, no behavior change
 * - 'image': route through the multimodal model + embedding_image column
 *   (visually-similar matching + image OCR text)
 * - 'both': run text + image searches in parallel and merge via
 *   weighted RRF (recall-leaning when the query is ambiguous)
 *
 * Parallel axis to intent/detail/salience/recency. Returned by
 * classifyQuery from one regex pass over the query.
 */
export type ModalityMode = 'text' | 'image' | 'both';

export interface QuerySuggestions {
  intent: QueryIntent;
  /** v0.29.0 detail mapping. entity→low, temporal/event→high, general→undefined. */
  suggestedDetail: 'low' | 'medium' | 'high' | undefined;
  /** v0.29.1 — emotional_weight + take_count boost. */
  suggestedSalience: SalienceMode;
  /** v0.29.1 — per-prefix age-decay boost. */
  suggestedRecency: RecencyMode;
  /** v0.36 — cross-modal routing axis. Defaults to 'text' when nothing matches. */
  suggestedModality: ModalityMode;
}

// ─────────────────────────────────────────────────────────
// Pattern banks (organized by axis they signal)
// ─────────────────────────────────────────────────────────

// Original v0.29.0 intent patterns. Drive .intent + .suggestedDetail.
const TEMPORAL_PATTERNS = [
  /\bwhen\b/i,
  /\blast\s+(met|meeting|call|conversation|chat|talked|spoke|seen|heard|time)\b/i,
  /\brecent(ly)?\b/i,
  /\bhistory\b/i,
  /\btimeline\b/i,
  /\bmeeting\s+notes?\b/i,
  /\bwhat('s| is| was)\s+new\b/i,
  /\blatest\b/i,
  /\bupdate(s)?\s+(on|from|about)\b/i,
  /\bhow\s+long\s+(ago|since)\b/i,
  /\b\d{4}[-/]\d{2}\b/i,
  /\blast\s+(week|month|quarter|year)\b/i,
];

const EVENT_PATTERNS = [
  /\bannounce[ds]?(ment)?\b/i,
  /\blaunch(ed|es|ing)?\b/i,
  /\braised?\s+\$?\d/i,
  /\bfund(ing|raise)\b/i,
  /\bIPO\b/i,
  /\bacquisition\b/i,
  /\bmerge[drs]?\b/i,
  /\bnews\b/i,
  /\bhappened?\b/i,
];

const ENTITY_PATTERNS = [
  /\bwho\s+is\b/i,
  /\bwhat\s+(is|does|are)\b/i,
  /\btell\s+me\s+about\b/i,
  /\bdescribe\b/i,
  /\bsummar(y|ize)\b/i,
  /\boverview\b/i,
  /\bbackground\b/i,
  /\bprofile\b/i,
  /\bwhat\s+do\s+(i|you|we)\s+know\b/i,
];

const FULL_CONTEXT_PATTERNS = [
  /\beverything\b/i,
  /\ball\s+(about|info|information|details)\b/i,
  /\bfull\s+(history|context|picture|story|details)\b/i,
  /\bcomprehensive\b/i,
  /\bdeep\s+dive\b/i,
  /\bgive\s+me\s+everything\b/i,
];

// v0.29.1 — recency-axis patterns
//
// Canonical patterns: queries asking for the authoritative / definitional
// answer. These signal recency='off' even when other axes match — UNLESS
// an explicit temporal bound is present (per D6 narrow exception).
const CANONICAL_PATTERNS = [
  /\bwho\s+is\b/i,
  /\bwhat\s+(is|are|does|means?)\b/i,
  /\bdefin(e|ition|ing)\b/i,
  /\bexplain\s+(what|how|why)\b/i,
  /\b(history|origin|background)\s+of\b/i,
  /\bconcept\s+of\b/i,
  /\boverview\s+of\b/i,
  /\btell\s+me\s+about\b/i,
  /\bcompiled\s+truth\b/i,
  /::|->|\.\w+\(/,
  /\b(function|class|method|module)\s+\w+/i,
  /\b(graph|traversal|backlinks?|inbound|outbound)\b/i,
];

// Aggressive recency: "today", "right now", "this morning", "just now".
const STRONG_RECENCY_PATTERNS = [
  /\btoday\b/i,
  /\bright\s+now\b/i,
  /\bthis\s+morning\b/i,
  /\bjust\s+now\b/i,
];

// Moderate recency: "what's going on", "latest", "recent", "this week",
// meeting prep, conversation recall, status updates.
const RECENCY_ON_PATTERNS = [
  /\bwhat'?s\s+(going\s+on|happening|new|latest|up)\b/i,
  /\b(latest|recent(ly)?|currently)\b/i,
  /\b(this|last|past)\s+(week|month|few\s+days|couple\s+days)\b/i,
  /\bmeeting\s+(prep|with|for|notes?|brief)\b/i,
  /\bbefore\s+(my|the|our)\s+(meeting|call|sync|chat)\b/i,
  /\bprep(are)?\s+(for|me)\b/i,
  /\bcatch(es|ing)?\b[\s\w]{0,15}\bup\b/i,  // "catch up", "catch me up", "catching X up"
  /\bremind\s+me\s+(what|about|of)\b/i,
  /\b(update|status|progress)\s+(on|with|from)\b/i,
];

// Per D6: explicit temporal bounds override canonical-wins. "Who is X today"
// → recency='on' (temporal bound wins). "Who is X" alone → recency='off'.
const EXPLICIT_TEMPORAL_BOUND_PATTERNS = [
  /\btoday\b/i,
  /\bright\s+now\b/i,
  /\bthis\s+morning\b/i,
  /\bthis\s+week\b/i,
  /\bsince\s+(launch|last|the|\d)/i,
  /\blast\s+\d+\s+(day|days|week|weeks|month|months)\b/i,
];

// v0.29.1 — salience-axis patterns
//
// Salience suggests "what matters in this brain right now" — when the user
// is asking about people/companies/deals in the current context, they
// usually want the emotionally-weighted + take-rich pages to surface.
// Salience patterns are a subset of recency-on patterns (meeting prep,
// catch-up, update language) plus people-centric phrasings.
const SALIENCE_ON_PATTERNS = [
  /\bwhat'?s\s+(going\s+on|happening|been\s+going|been\s+up)\b/i,
  /\bcatch(es|ing)?\b[\s\w]{0,15}\bup\b/i,
  /\bremind\s+me\s+(what|about|of)\b/i,
  /\bprep(are)?\s+(for|me)\b/i,
  /\bbefore\s+(my|the|our)\s+(meeting|call|sync|chat)\b/i,
  /\bmeeting\s+(prep|with|for|brief)\b/i,
  /\b(update|status|progress)\s+(on|with|from)\b/i,
  /\bwhat\s+matters\b/i,
  /\bwhat'?s\s+important\b/i,
];

// v0.36 cross-modal wave — modality-axis patterns (D6).
//
// CROSS_MODAL_PATTERNS fires the 'image' modality when the query explicitly
// names visual artifacts ("show me photos", "find images of", "screenshot of",
// "what does X look like", "diagram of"). Module-scope const so regexes
// compile once at module load (D15).
//
// Conservative on purpose — false positives cost "one cheaper image search
// where text might have worked." False negatives cost nothing (the legacy
// text path still runs). The LLM-intent escalation in Commit 4 catches
// genuinely ambiguous phrasings.
//
// CJK note: the English patterns are unreachable for Chinese and Japanese
// queries, because JavaScript's `\b` is an ASCII word boundary.
// A Han or Kana character is not a `\w` character, so no boundary ever exists
// beside it — /\b照片\b/ cannot match the string "照片". CJK queries therefore
// always fell through to 'text' and never reached the embedding_image column,
// however many image chunks the brain holds.
//
// The CJK bank anchors on structure instead of word boundaries: the possessive
// 的 / の, a picture measure word (张/幅/组), or an action verb next to the
// visual noun. Conservatism matches the English bank on purpose — a bare
// visual noun ("截图", like a bare "screenshot") stays 'text', because 'image'
// modality is exclusive (D9 skips keyword search), so a false positive drops
// text results rather than merely adding an image search.
const CJK_VISUAL_NOUNS =
  '照片|相片|图片|圖片|图像|圖像|截图|截圖|截屏|画面|畫面|影像|图表|圖表|' +
  '写真|画像|イラスト|スクショ|スクリーンショット';

const CJK_VISUAL_VERBS =
  '找|搜|搜索|查找|翻出|给我|給我|看看|显示|顯示|展示';

const CROSS_MODAL_PATTERNS_CJK: RegExp[] = [
  // "蓝色羽绒服的照片" / "小花笑的图片" / "那张截图" / "猫の写真"
  new RegExp(`(的|の|[张張幅组組])\\s*(${CJK_VISUAL_NOUNS})`),
  // verb-initial (zh): "找一下蓝色羽绒服照片"
  new RegExp(`(${CJK_VISUAL_VERBS})[^\\n]{0,20}?(${CJK_VISUAL_NOUNS})`),
  // verb-final (ja): "写真を見せて" / "画像を探して"
  new RegExp(`(${CJK_VISUAL_NOUNS})\\s*(を|が|は)?\\s*(見せ|見たい|探し|見つけ)`),
  // "X 长什么样" — the CJK form of "what does X look like"
  /长(得)?(什么|甚么|啥)样|長(得)?(什麼|甚麼)樣/,
];

const CROSS_MODAL_PATTERNS: RegExp[] = [
  /\b(show|find|get|pull)\s+(me\s+)?(the\s+)?(photos?|images?|pictures?|pics?|screenshots?)\b/i,
  /\b(photos?|images?|pictures?|pics?|screenshots?)\s+(of|from|at|with|showing|featuring)\b/i,
  /\bwhat\s+does\s+[\w\s']{1,40}?\s+look\s+like\b/i,
  /\b(whiteboard|diagram|slide|screenshot|infographic|chart)s?\s+(of|from|about|showing)\b/i,
  /\bdiagram\s+(of|for|showing)\b/i,
  /\bvisual(s|ly)?\s+(of|from|about|showing|representation)\b/i,
  ...CROSS_MODAL_PATTERNS_CJK,
];

// v0.36 cross-modal wave (Commit 4 prep): visual nouns that combined with
// ambiguous-pronoun phrasings ("any pics from last week's offsite?") trigger
// the optional LLM intent escalation. Subset of cross-modal patterns plus
// looser noun-form matches.
const AMBIGUOUS_MODALITY_NOUNS: RegExp[] = [
  /\b(photo|image|picture|pic|screenshot|diagram|whiteboard|slide|chart)s?\b/i,
  /\blook(s|ed)?\s+like\b/i,
  /\bvisual(s|ly)?\b/i,
];

// Pronoun + filler markers that signal "the user is referencing something
// they can't quite name" — combined with AMBIGUOUS_MODALITY_NOUNS, triggers
// the LLM tie-break in Commit 4.
const AMBIGUOUS_REFERENCE_MARKERS: RegExp[] = [
  // Match all the visual nouns (pic/pics, picture/pictures, photo/photos, image/images,
  // screenshot/screenshots, diagram/diagrams, whiteboard/whiteboards, slide/slides, chart/charts).
  /\b(any|some|that|those|these|the)\s+(pic|pics|picture|pictures|photo|photos|image|images|screenshot|screenshots|diagram|diagrams|whiteboard|whiteboards|slide|slides|chart|charts)\b/i,
  /\bfrom\s+(last|this|the)\s+(week|month|year|offsite|meeting|hackathon|deck)\b/i,
];

// ─────────────────────────────────────────────────────────
// #4415 — per-brain pattern extensions (search.intent_patterns)
// ─────────────────────────────────────────────────────────

/**
 * Every shipped bank above is English-only `\b`-anchored regex, so a brain
 * queried in another language classified 'general' with recency AND salience
 * permanently 'off' — the ranking stages never executed at all. The
 * `search.intent_patterns` config key (same operator-extension shape as
 * `emotional_weight.high_tags`) merges per-brain patterns OVER the shipped
 * banks: a JSON object of bank-name → array of regex sources, e.g.
 *
 *   {"recency_on": ["לאחרונה", "מה חדש"], "strong_recency": ["היום"]}
 *
 * Sources compile with the 'iu' flags ('i' fallback when 'u' rejects the
 * source). Extensions only ever ADD matches — the shipped banks stay in
 * force, and a bad config (unparseable JSON, unknown bank, invalid regex)
 * fail-opens to the shipped behavior per entry.
 */
export const INTENT_PATTERN_BANKS = [
  'temporal', 'event', 'entity', 'full_context', 'canonical',
  'strong_recency', 'recency_on', 'salience_on', 'explicit_temporal_bound',
] as const;
export type IntentPatternBank = (typeof INTENT_PATTERN_BANKS)[number];

/**
 * Typed builder for an empty per-bank pattern record. A plain
 * `Object.fromEntries(...) as Record<...>` is rejected by tsc 5.9 (TS2352:
 * fromEntries returns `{ [k: string]: never[] }`, which doesn't overlap the
 * literal-keyed Record). The loop below assigns EVERY member of
 * INTENT_PATTERN_BANKS, so the narrowing assertion on the empty literal is
 * safe by construction.
 */
function emptyBankSet(): Record<IntentPatternBank, RegExp[]> {
  const out = {} as Record<IntentPatternBank, RegExp[]>;
  for (const b of INTENT_PATTERN_BANKS) out[b] = [];
  return out;
}

const EXTENSIONS: Record<IntentPatternBank, RegExp[]> = emptyBankSet();

// Idempotence cache: recompile only when the raw config value changes
// (applyIntentPatternConfig runs per search on the hot path).
let appliedRaw: string | null | undefined;
let appliedErrors: string[] = [];

/**
 * Compile the raw `search.intent_patterns` config value INTO a bank set
 * (cleared first; null/undefined/'' leaves it empty). Returns per-entry
 * compile errors (empty = fully applied). Never throws. Shared by the
 * process-global seam and the per-engine cache.
 */
function compileIntentPatternConfig(
  raw: string | null | undefined,
  into: Record<IntentPatternBank, RegExp[]>,
): string[] {
  const errors: string[] = [];
  for (const bank of INTENT_PATTERN_BANKS) into[bank].length = 0;
  if (!raw) return errors;
  let parsed: unknown;
  try {
    parsed = JSON.parse(raw);
  } catch (e) {
    errors.push(`search.intent_patterns is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
    return errors;
  }
  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
    errors.push('search.intent_patterns must be a JSON object of bank-name → array of regex sources');
    return errors;
  }
  for (const [bank, sources] of Object.entries(parsed as Record<string, unknown>)) {
    if (!(INTENT_PATTERN_BANKS as readonly string[]).includes(bank)) {
      errors.push(`unknown pattern bank '${bank}' (valid: ${INTENT_PATTERN_BANKS.join(', ')})`);
      continue;
    }
    if (!Array.isArray(sources)) {
      errors.push(`bank '${bank}' must be an array of regex sources`);
      continue;
    }
    for (const src of sources) {
      if (typeof src !== 'string' || src.length === 0) {
        errors.push(`bank '${bank}': entries must be non-empty strings`);
        continue;
      }
      try {
        into[bank as IntentPatternBank].push(new RegExp(src, 'iu'));
      } catch {
        try {
          into[bank as IntentPatternBank].push(new RegExp(src, 'i'));
        } catch (e) {
          errors.push(`bank '${bank}': invalid regex '${src}': ${e instanceof Error ? e.message : String(e)}`);
        }
      }
    }
  }
  return errors;
}

/**
 * Compile + install the `search.intent_patterns` config value (raw string
 * from engine.getConfig; null/undefined/'' clears the extensions). Returns
 * the per-entry compile errors (empty = fully applied). Never throws.
 * Process-wide DEFAULT state — sync classifyQuery callers that don't thread
 * a bank set read it. Engine-bound callers use loadEngineIntentPatterns.
 */
export function applyIntentPatternConfig(raw: string | null | undefined): string[] {
  if (raw === appliedRaw) return appliedErrors;
  appliedRaw = raw;
  appliedErrors = compileIntentPatternConfig(raw, EXTENSIONS);
  return appliedErrors;
}

/** Test seam: reset the process-wide extension state AND the per-engine cache. */
export function clearIntentPatternConfigForTests(): void {
  appliedRaw = undefined;
  appliedErrors = [];
  for (const bank of INTENT_PATTERN_BANKS) EXTENSIONS[bank].length = 0;
  engineIntentStates = new WeakMap();
}

/**
 * Short stable fingerprint of a raw `search.intent_patterns` config value —
 * folded into the query-cache knobs hash (mode.ts `ipat=`) because the
 * patterns change classification (intent weights + auto salience/recency/
 * detail) and therefore results. 'none' for unset/empty config so legacy
 * and pattern-less brains hash identically.
 */
export function intentPatternFingerprint(raw: string | null | undefined): string {
  if (!raw) return 'none';
  return createHash('sha256').update(raw).digest('hex').slice(0, 12);
}

/** Per-engine compiled pattern state (wave-g). */
export interface EngineIntentPatternState {
  banks: Record<IntentPatternBank, RegExp[]>;
  /** intentPatternFingerprint of the applied raw config. */
  fingerprint: string;
  /** Per-entry compile errors from the last (re)compile. */
  errors: string[];
  /** Raw config value the banks were compiled from. */
  raw: string | null | undefined;
  /** Last successful-or-attempted fetch time (ms epoch) — TTL anchor. */
  fetchedAt: number;
}

/**
 * How long a per-engine compiled pattern set is trusted before the next
 * classify re-reads `search.intent_patterns`. There is no config-write
 * invalidation seam (engines have no write hooks), so a short TTL bounds
 * both the hot-path getConfig rate AND the staleness window after a
 * `gbrain config set`.
 */
export const INTENT_PATTERN_TTL_MS = 30_000;

let engineIntentStates = new WeakMap<object, EngineIntentPatternState>();

/**
 * The engine's compiled `search.intent_patterns` state, cached per engine
 * object with a short TTL (see INTENT_PATTERN_TTL_MS). Fail-open: a
 * throwing getConfig keeps the last-compiled banks (shipped-only on first
 * failure) and still advances the TTL anchor so a down config plane isn't
 * hammered per query. Never throws.
 */
export async function loadEngineIntentPatterns(
  engine: { getConfig(key: string): Promise<string | null> },
): Promise<EngineIntentPatternState> {
  const now = Date.now();
  let state = engineIntentStates.get(engine);
  if (state && now - state.fetchedAt < INTENT_PATTERN_TTL_MS) return state;
  if (!state) {
    state = { banks: emptyBankSet(), fingerprint: 'none', errors: [], raw: undefined, fetchedAt: now };
    engineIntentStates.set(engine, state);
  }
  state.fetchedAt = now;
  try {
    const raw = await engine.getConfig('search.intent_patterns');
    if (raw !== state.raw) {
      state.raw = raw;
      state.errors = compileIntentPatternConfig(raw, state.banks);
      state.fingerprint = intentPatternFingerprint(raw);
    }
  } catch { /* fail-open: keep the last-compiled banks */ }
  return state;
}

/**
 * classifyQuery with the brain's `search.intent_patterns` merged over the
 * shipped banks — the wrapper hybridSearch calls (it has the engine; the
 * classifier stays sync). Per-engine banks (wave-g): a multi-engine process
 * never applies one brain's patterns to another brain's queries, and the
 * config read is TTL-cached off the hot path. Fail-open: an unreadable
 * config leaves the shipped banks in force.
 */
export async function classifyQueryWithBrainPatterns(
  engine: { getConfig(key: string): Promise<string | null> },
  query: string,
): Promise<QuerySuggestions> {
  const state = await loadEngineIntentPatterns(engine);
  return classifyQuery(query, state.banks);
}

// ─────────────────────────────────────────────────────────
// Classifier
// ─────────────────────────────────────────────────────────

function matches(patterns: RegExp[], q: string): boolean {
  for (const re of patterns) if (re.test(q)) return true;
  return false;
}

/** Shipped bank OR the configured extension bank (#4415). Defaults to the
 * process-global extensions; engine-bound callers thread their own set. */
function matchesBank(
  bank: IntentPatternBank,
  shipped: RegExp[],
  q: string,
  ext: Record<IntentPatternBank, RegExp[]> = EXTENSIONS,
): boolean {
  return matches(shipped, q) || matches(ext[bank], q);
}

/**
 * Classify a query and return all three axis suggestions.
 *
 * Resolution rules:
 *   - intent:            original v0.29.0 priority (full-context > temporal > event > entity > general)
 *   - suggestedDetail:   intent → detail mapping (entity=low, temporal/event=high)
 *   - suggestedRecency:  STRONG_RECENCY > RECENCY_ON; CANONICAL wins UNLESS
 *                        EXPLICIT_TEMPORAL_BOUND also matches; default 'off'
 *   - suggestedSalience: SALIENCE_ON; CANONICAL wins UNLESS
 *                        EXPLICIT_TEMPORAL_BOUND; default 'off'
 *
 * Note: salience and recency are independent. A "what's going on with X"
 * query gets BOTH on; "who is X" gets BOTH off; "today's news" gets
 * recency='strong' but salience='off' (the user wants newest, not
 * emotionally-weighted).
 */
export function classifyQuery(
  query: string,
  ext: Record<IntentPatternBank, RegExp[]> = EXTENSIONS,
): QuerySuggestions {
  const intent = classifyQueryIntent(query, ext);
  const suggestedDetail = intentToDetail(intent);

  const hasCanonical = matchesBank('canonical', CANONICAL_PATTERNS, query, ext);
  const hasTemporalBound = matchesBank('explicit_temporal_bound', EXPLICIT_TEMPORAL_BOUND_PATTERNS, query, ext);
  const hasStrongRecency = matchesBank('strong_recency', STRONG_RECENCY_PATTERNS, query, ext);
  const hasRecencyOn = matchesBank('recency_on', RECENCY_ON_PATTERNS, query, ext);
  const hasSalienceOn = matchesBank('salience_on', SALIENCE_ON_PATTERNS, query, ext);

  // Recency axis
  let suggestedRecency: RecencyMode;
  if (hasCanonical && !hasTemporalBound) {
    suggestedRecency = 'off';
  } else if (hasStrongRecency) {
    suggestedRecency = 'strong';
  } else if (hasRecencyOn) {
    suggestedRecency = 'on';
  } else {
    suggestedRecency = 'off';
  }

  // Salience axis (orthogonal)
  let suggestedSalience: SalienceMode;
  if (hasCanonical && !hasTemporalBound) {
    suggestedSalience = 'off';
  } else if (hasSalienceOn) {
    suggestedSalience = 'on';
  } else {
    suggestedSalience = 'off';
  }

  // v0.36 cross-modal — modality axis. Independent of intent/detail/salience/recency.
  // Conservative default 'text'; only flips to 'image' on explicit cross-modal regex match.
  // 'both' is reserved for explicit per-call opts (LLM-intent escalation in Commit 4
  // can also produce 'both' via tie-break).
  const suggestedModality: ModalityMode = matches(CROSS_MODAL_PATTERNS, query) ? 'image' : 'text';

  return { intent, suggestedDetail, suggestedSalience, suggestedRecency, suggestedModality };
}

/**
 * v0.36 — heuristic gate for the optional LLM intent escalation (Commit 4).
 *
 * Fires when the query contains a visual noun ("any pics", "the diagram",
 * "what does it look like") combined with an ambiguous reference marker
 * ("from last week's offsite"). These are the phrasings the conservative
 * regex misses but a Haiku tie-break catches.
 *
 * Returns false for unambiguous text queries (no LLM call burned). Returns
 * false for queries the regex ALREADY caught (no need to tie-break a
 * confident classification). Returns true only for the narrow band where
 * the LLM call earns its $0.0001 cost.
 *
 * Pure function. No LLM call. No DB access. Used by hybridSearch's
 * escalation branch only when `search.cross_modal.llm_intent: true`.
 */
export function isAmbiguousModalityQuery(query: string): boolean {
  // Already-confident classification → no LLM needed.
  if (matches(CROSS_MODAL_PATTERNS, query)) return false;

  const hasVisualNoun = matches(AMBIGUOUS_MODALITY_NOUNS, query);
  if (!hasVisualNoun) return false;

  const hasReferenceMarker = matches(AMBIGUOUS_REFERENCE_MARKERS, query);
  return hasReferenceMarker;
}

// ─────────────────────────────────────────────────────────
// v0.29.0 compatibility shims
// ─────────────────────────────────────────────────────────

/** v0.29.0 intent type. Preserved verbatim for back-compat. */
export function classifyQueryIntent(
  query: string,
  ext: Record<IntentPatternBank, RegExp[]> = EXTENSIONS,
): QueryIntent {
  if (matchesBank('full_context', FULL_CONTEXT_PATTERNS, query, ext)) return 'temporal';
  if (matchesBank('temporal', TEMPORAL_PATTERNS, query, ext)) return 'temporal';
  if (matchesBank('event', EVENT_PATTERNS, query, ext)) return 'event';
  // v0.46.15 (Cat 13): concept BEFORE entity — definitional paraphrases
  // ("What is the ownership economy?") previously classified entity and got
  // the keyword tilt, making hybrid LOSE to its own vector arm on
  // paraphrase queries. Full-context/temporal/event keep their queries;
  // only entity/general-bound queries can re-route here.
  if (isConceptShapedQuery(query)) return 'concept';
  if (matchesBank('entity', ENTITY_PATTERNS, query, ext)) return 'entity';
  return 'general';
}

/** v0.29.0 mapping. */
export function intentToDetail(intent: QueryIntent): 'low' | 'medium' | 'high' | undefined {
  switch (intent) {
    case 'entity': return 'low';
    case 'temporal': return 'high';
    case 'event': return 'high';
    // v0.46.15: concept queries keep the default detail — the vector-lean
    // weights (intent-weights.ts) are the mechanism, not source filtering.
    case 'concept': return undefined;
    case 'general': return undefined;
  }
}

/** v0.29.0 helper. Routes through classifyQuery internally. */
export function autoDetectDetail(query: string): 'low' | 'medium' | 'high' | undefined {
  return classifyQuery(query).suggestedDetail;
}

// ─────────────────────────────────────────────────────────
// #2416 — concept-shaped query detection (CLI nudge)
// ─────────────────────────────────────────────────────────

// Fuzzy-quantifier / landscape cues. A concept-shaped question asks for a
// SET defined by meaning ("all the X that do Y", "the landscape of Z") —
// exactly where `query`'s multi-query expansion recovers synonym- and
// outcome-phrased matches that the expansion-off `search` op can miss.
//
// Deliberately EXCLUDED cues (owned by other routers — a nudge toward
// `query` on these would fight their descriptions):
//   - "who are the …"        → find_experts
//   - bare "anything …"      → get_recent_salience / find_anomalies
// v0.46.15 (Cat 13): the ONE shared concept cue bank — consumed by BOTH the
// intent classifier (ranking weights) and the CLI nudge below. Two drifting
// concept definitions was the DRY failure the outside voice flagged (R2-11).
//
// Landscape/quantifier cues: the query asks for a SET defined by meaning.
export const CONCEPT_CUE_PATTERNS: RegExp[] = [
  /\b(all|every)\b.+\b(that|who|which|doing|with|about|related to)\b/i,
  /\b(find|list|show)\s+(all|every|everything)\b/i,
  /\beverything\s+(about|on|matching|related)\b/i,
  /\bthe\s+(landscape|ecosystem|space|universe)\s+of\b/i,
  /\b(landscape|ecosystem)\s+(of|around)\b/i,
  /\bwhich\s+\w+[\w\s]*\b(do|does|are|have|use|work)\b/i,
];

// Definitional-paraphrase cues (v0.46.15): the query asks what an IDEA means
// — exactly where the vector arm wins and the keyword tilt hurt (Cat 13:
// hybrid 47.0 nDCG@5 vs bare vector 49.1 on paraphrase probes).
// DELIBERATELY DISJOINT from FULL_CONTEXT_PATTERNS ("everything about X",
// "all about X" stay full-context → temporal ordering unchanged).
export const CONCEPT_DEFINITIONAL_PATTERNS: RegExp[] = [
  // Lowercase MULTI-WORD subject required (adversarial ship-review F5): the
  // identity wave's own premise is that users type NAMES lowercase — "what
  // is saoirse working on" / "what do i know about galewright" must keep the
  // entity keyword tilt. Concepts in definitional paraphrases are noun
  // PHRASES ("ownership economy", "founder liquidity"); a single lowercase
  // subject word is undecidable without the alias table, so it conservatively
  // stays entity (pre-wave behavior).
  /\b[Ww]hat\s+(is|are)\s+(the\s+)?[a-z][\w'’-]*\s+[a-z]/,               // "What is the ownership economy"
  /\b[Ww]hat\s+do\s+(i|you|we)\s+know\s+about\s+[a-z][\w'’-]*\s+[a-z]/,  // multi-word lowercase subject
  /\b(notes|ideas|thinking|thoughts|writing)\s+(on|about)\b/i,
  /\bways\s+to\b/i,
  /\bhow\s+to\s+think\s+about\b/i,
  /\bconcept\s+of\b/i,
];

/**
 * Status-verb anti-signal for the DEFINITIONAL route only (adversarial F5):
 * "what is <name> working on / up to" asks what an entity is DOING, not what
 * a concept IS — the definitional cue is a false match there. Applies only
 * in isConceptShapedQuery (the ranking route); the CLI nudge's vocabulary is
 * deliberately untouched.
 */
const CONCEPT_STATUS_ANTI_RE = /\b(working on|up to|doing|saying|talking about|focused on|meeting with)\b/i;

// Exact-identifier anti-signals: the query names a specific thing, so the
// cheap `search` op is the right tool and a nudge would be noise.
const CONCEPT_ANTI_PATTERNS: RegExp[] = [
  /["'“”][^"'“”]+["'“”]/,               // quoted phrase — exact-match intent
  /\b[a-z0-9]+(?:-[a-z0-9]+){1,}\b/,    // slug-like token (kebab-case)
];

/**
 * v1-conservative proper-noun anti-signal (v0.46.15): any capitalized token
 * that is NOT sentence-initial is treated as evidence the query names a
 * specific entity — the entity keyword tilt is correct there, not the
 * concept vector lean. Sentence-initial capitalization alone never blocks.
 */
function hasMidSentenceCapital(q: string): boolean {
  const re = /\s(\p{Lu})/gu;
  for (const m of q.matchAll(re)) {
    const idx = m.index ?? 0;
    // Walk back past the whitespace to the previous non-space char.
    let i = idx;
    while (i >= 0 && /\s/.test(q[i])) i--;
    if (i < 0) continue; // start of string → sentence-initial
    if (!/[.!?:;\n\r•\-(["“]/.test(q[i])) return true;
  }
  return false;
}

/**
 * v0.46.15 — concept-shape detection for the INTENT classifier. A query is
 * concept-shaped when it carries a landscape/quantifier OR definitional-
 * paraphrase cue, and NO exact-identifier or proper-noun anti-signal.
 * Precision-biased: quoted phrases, slugs, mid-sentence capitalized tokens,
 * and sub-3-word queries never trigger.
 */
export function isConceptShapedQuery(query: string): boolean {
  const q = query.trim();
  if (q.split(/\s+/).length < 3) return false; // bare token / proper-noun lookup
  const definitional = matches(CONCEPT_DEFINITIONAL_PATTERNS, q);
  if (!matches(CONCEPT_CUE_PATTERNS, q) && !definitional) return false;
  if (matches(CONCEPT_ANTI_PATTERNS, q)) return false;
  if (hasMidSentenceCapital(q)) return false;
  // Definitional-route only (F5): a status verb means the subject is an
  // entity being asked about, not a concept being defined.
  if (definitional && !matches(CONCEPT_CUE_PATTERNS, q) && CONCEPT_STATUS_ANTI_RE.test(q)) return false;
  return true;
}

/**
 * True when a query is concept-shaped for the CLI NUDGE (#2416). Consumes
 * the SAME shared cue/anti banks as the intent detector above (single
 * concept vocabulary — R2-11), composed differently for a different
 * decision: the nudge steers `search` → `query` (breadth/expansion), so it
 * keeps the landscape-cue subset, skips the proper-noun anti-signal (a
 * landscape query about a capitalized techonym still wants expansion), and
 * only backs off when the classifier is confident the query names an
 * ENTITY. The ranking detector is stricter because a wrong vector-lean
 * costs precision; a wrong nudge costs one stderr line.
 */
export function looksConceptShaped(query: string): boolean {
  const q = query.trim();
  if (q.split(/\s+/).length < 3) return false; // bare token / proper-noun lookup
  if (!matches(CONCEPT_CUE_PATTERNS, q)) return false;
  if (matches(CONCEPT_ANTI_PATTERNS, q)) return false;
  if (classifyQueryIntent(q) === 'entity') return false;
  return true;
}

/**
 * One-line CLI hint steering a concept-shaped `search` toward `query`.
 * Returns null when the query is not concept-shaped. Message generation
 * lives here (not in cli.ts) so the full string is unit-testable; the CLI
 * wiring is a two-liner per dispatch path, stderr only, `--quiet`-gated.
 */
export function conceptNudge(query: string): string | null {
  if (!looksConceptShaped(query)) return null;
  const preview = query.length > 60 ? `${query.slice(0, 57)}...` : query;
  return (
    `hint: concept-shaped question — try \`gbrain query "${preview}" --expand\` ` +
    `(multi-query expansion can recover synonym-phrased matches search can miss). ` +
    `A nonzero search count is not proof of completeness.`
  );
}

// ─────────────────────────────────────────────────────────
// #1663 — query-shape router (factual vs open)
// ─────────────────────────────────────────────────────────

/**
 * #1663 — coarse query SHAPE, orthogonal to intent:
 *
 *   'factual' — a bounded lookup with a small, checkable answer (who/when/
 *               where/which, attribute possessives, quoted names, slug-ish
 *               tokens, short entity lookups). Retrieval either has the row
 *               or it doesn't; the CRAG gate's retrieval-side escalation is
 *               worth one re-run here.
 *   'open'    — synthesis-shaped (how/why/explain/summarize/compare,
 *               long multi-clause). When retrieval confidence is weak on an
 *               open query, MORE retrieval rarely fixes it — the honest
 *               escalation target is `think` (multi-round gather+synthesis).
 *
 * Consumed by the CRAG confidence gate (crag.ts + the `query` op) and
 * surfaced in the retrieval response meta for auditability.
 */
export type QueryShape = 'factual' | 'open';

const OPEN_SHAPE_PATTERNS: RegExp[] = [
  /^\s*(how|why)\b/i,
  /\b(explain|describe|summariz\w*|overview of|walk me through|brainstorm|compare|contrast|catch me up|tell me about|history of)\b/i,
  /\bwhat\s+do\s+(i|we|you)\s+know\s+about\b/i,
  /\b(pros\s+and\s+cons|trade-?offs|implications|open\s+questions)\b/i,
];

const FACTUAL_SHAPE_PATTERNS: RegExp[] = [
  /^\s*(who|whom|whose|when|where|which)\b/i,
  // Attribute possessive / attribute-of lookups ("alice's email", "the url of X").
  /\b(email|phone|address|birthday|date|deadline|url|link|title|name|number|id|slug|handle)\b/i,
  /["'“”][^"'“”]+["'“”]/, // quoted phrase — exact-match intent
  /\b[a-z0-9]+(?:-[a-z0-9]+){1,}\b/i, // slug-like token
];

/** Word-count threshold above which an unmatched query reads as open-ended. */
const OPEN_SHAPE_TOKEN_THRESHOLD = 9;

export function classifyQueryShape(query: string): QueryShape {
  const q = query.trim();
  if (!q) return 'open';
  // Explicit factual leads win over embedded open verbs: "who explained the
  // outage" is still a who-lookup.
  if (/^\s*(who|whom|whose|when|where|which)\b/i.test(q)) return 'factual';
  if (matches(OPEN_SHAPE_PATTERNS, q)) return 'open';
  if (isConceptShapedQuery(q)) return 'open'; // set-by-meaning ≈ open-ended
  if (matches(FACTUAL_SHAPE_PATTERNS, q)) return 'factual';
  // Unmatched: short queries are lookups; long multi-clause reads as open.
  return q.split(/\s+/).length > OPEN_SHAPE_TOKEN_THRESHOLD ? 'open' : 'factual';
}

/**
 * #1663 — gate for the structural exact-lookup tier (exact-lookup.ts): a
 * query short enough to plausibly BE a page identity (slug, exact title,
 * declared alias). Mirrors the alias hop's ≤6-token guard; slug-shaped
 * single tokens ('people/alice-example') always qualify. Pure + cheap —
 * called per query on the hot path.
 */
export function isLookupShapedQuery(query: string): boolean {
  const q = query.trim();
  if (!q) return false;
  if (!/\s/.test(q) && q.includes('/')) return true; // slug-shaped
  return q.split(/\s+/).length <= 6;
}