Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
130 KB
Raw Blame
/**
 * Shared link/timeline extraction utilities.
 *
 * Used by:
 *   - src/commands/extract.ts             (batch DB + FS extraction — `gbrain extract links|timeline|all`)
 *   - src/commands/backlinks.ts           (filesystem walk, legacy)
 *   - src/core/operations.ts put_page     (auto-link post-hook)
 *
 * All functions are PURE (no DB access). The DB lives in the engine; these
 * utilities turn page content into candidates that callers persist via engine
 * methods. Auto-link config is the one impure helper (reads engine.getConfig).
 */

import type { BrainEngine, LinkBatchInput } from './engine.ts';
import type { PageType, EffectiveDateSource } from './types.ts';
import { ensureWellFormed } from './text-safe.ts';
import { stripCodeBlocks } from './markdown-code.ts';
import { maskLinksFence } from './links-fence.ts';
import { targetTakesVerb } from './link-target-roles.ts';
import { inSuppressedRange, roleTriggerText, rolePriorSuppressedRanges } from './machine-sections.ts';
import { statedRelationTypes } from './line-grammar.ts';
import { isValidSourceId } from './source-id.ts';
import { isDatedTimelineLine, parseInlineCitationTimelineEntries, TIMELINE_LINE_RE, TIMELINE_LINE_RE_CN } from './timeline-citations.ts';
import { isMaterializedMarkerLine } from './timeline-marker.ts';
import { slugifyPath, slugifySegment } from './sync.ts';
import { exactSlugCandidates } from './exact-slug-candidates.ts';
export { EXACT_SLUG_SHAPE_RE, exactSlugCandidates } from './exact-slug-candidates.ts';
import { SLUG_WORD_CHARS, SLUG_VARIATION_SELECTORS_RE } from './cjk.ts';
import { foldNonDecomposingLatin } from './latin-fold.ts';
import { isIdentityEntity, sameEntityName } from './entities/resolve.ts';
// #3190: pack-aware link typing. link-inference imports only manifest-v1
// (zod) + redos-guard (node:vm) — no cycle back into this module.
import type { SchemaPackManifest } from './schema-pack/manifest-v1.ts';
import { inferLinkTypeFromPack, frontmatterLinkTypeFromPack, ownsAttendanceInference } from './schema-pack/link-inference.ts';
import { PageRegexBudget } from './schema-pack/redos-guard.ts';
import { UNIT_VERB_RULES, typingUnitEnabled, unitOfRule, unitVerbVeto, type TypingUnit } from './link-typing-units.ts';
import { deriveTemporalEvidence, rowKey, type DerivedTransition } from './link-temporal-evidence.ts';
import { buildRelationshipState, relationSemantics, type AssertionTense, type Stint } from './link-validity.ts';

/**
 * #3190: the slice of a schema-pack manifest link extraction consumes.
 * Callers thread the ACTIVE pack's manifest (loadActivePackForLocalEngine /
 * loadActivePackBestEffort → `.manifest`); null/undefined keeps the legacy
 * in-code inference exactly as before.
 */
export type LinkExtractionPack = Pick<SchemaPackManifest, 'link_types' | 'frontmatter_links'> & Partial<Pick<SchemaPackManifest, 'page_types'>>;

export { stripCodeBlocks } from './markdown-code.ts';
export { parseInlineCitationTimelineEntries, type InlineCitationTimelineCandidate } from './timeline-citations.ts';

/**
 * v0.42.7 — link-extraction version stamp. Bump this ISO timestamp whenever the
 * shape of `extractPageLinks` / `inferLinkType` / `parseTimelineEntries` changes
 * meaningfully, so the extraction freshness watermark (`pages.links_extracted_at`)
 * treats every previously-stamped page as stale and re-extracts it on the next
 * `gbrain extract --stale` sweep. Same role CHUNKER_VERSION plays for chunking.
 *
 * Consumed by `countStalePagesForExtraction` / `listStalePagesForExtraction`
 * (both engines) and the `links_extraction_lag` doctor check: a page is stale
 * when `links_extracted_at IS NULL OR links_extracted_at < LINK_EXTRACTOR_VERSION_TS
 * OR updated_at > links_extracted_at`. It is an ISO-8601 string (NOT a number) —
 * the column is TIMESTAMPTZ and the predicate binds it as `::timestamptz`.
 */
// 2026-10-02: eval wave N12-6 — a `Participants:` line (plain or bold) or a
// `## Participants` section is attendance evidence like its `Attendees`
// twin, so meeting pages written with it re-extract and gain attended edges.
// 2026-10-01: eval wave N9-2/N9-3/N12-7 — schema-pack frontmatter mappings
// keep FRONTMATTER_LINK_MAP's declared direction (company `investors:` is
// investor -> company, meeting `attendees:` is person -> meeting), and a
// pack's `attended` verb on a meeting page follows canonical evidence-gated
// attendance, so edges the legacy gbrain-base pack stored backwards (or typed
// attended from a notes mention) re-derive on `extract --stale`.
// 2026-09-30: #5749 — with link_resolution.global_basename on, a unique
// basename match resolves a frontmatter wikilink before the fuzzy and live
// keyword steps, so edges the managed stale sweep re-pointed at a transcript
// re-extract back to the named page on the next `extract --stale`.
// 2026-09-30: #5765 — a bold `**Attendees:**` label before a bare link list is
// attendance evidence (the meeting-ingestion template wrote it), so meeting
// pages filed with it re-extract and gain their attended edges.
// 2026-09-09: #4985 — normalizeBasename strips Unicode variation selectors (twin
// of slugifySegment), so emoji+VS16 wikilinks re-resolve to the clean slug.
// 2026-09-09 (same wave): #4977 — the page-role prior no longer applies to
// links inside the machine-written list sections rolePriorSuppressedRanges
// matches (Timeline, See also, Related, Facts, Sources, Links, Email mention
// links, Backlinks, Significant moments), so pre-fix extractions re-run.
// 2026-09-06: #4873 — pass 1b accepts a leading `./` (and, same wave, the
// `../` / `./../` sibling forms + the folded bare-wikilink grammar), so pages
// whose links were pruned by the sweep reconcile re-extract on `extract --stale`.
// 2026-08-21: re-bumped for #2367 — normalizeBasename semantics changed
// (non-Latin scripts kept, accents folded like the slug grammar), so
// pre-#2367 extractions must re-run to pick up the newly-resolvable links.
// Subsumes the 2026-08-19 fix-wave-i bump (#3466 unevidenced people/ ->
// companies/ adjacency infers 'mentions', not 'works_at'; #2576 bug-2
// DIR_PATTERN whitelist no longer drops non-whitelisted-directory links).
// The watermark MUST NOT be in the future: the stamp path clamps
// links_extracted_at up to the watermark (so a fresh extraction isn't
// immediately re-listed), which means a future watermark masks concurrent
// edits until that date — the exact race D4 guards (test/extract-stale.test.ts).
// The converse limitation is inherent and accepted: a stamp written by
// PRE-wave code after this date reads as fresh and won't re-extract until
// the page is next edited; no fixed watermark can cover code that keeps
// running past it.
// 2026-10-02: hyphen-run basenames resolve (#5623); 2026-10-05: temporal edges derive dated evidence on extraction.
// 2026-10-05T03: typed relation lines (core/line-grammar.ts) state their link's type; a per-edge verb that
// belongs to another link in the window no longer types this one; "joined [X] as <role>" reads as works_at.
// 2026-10-08: held-out-confirmed Q2 units U1, U3, U4 (core/link-typing-units.ts). Re-extract so pages pick these up.
// A bump needs its entry in EXTRACTOR_BUMP_NOTES (link-extraction-watermark.ts), copied into the CHANGELOG at ship.
export const LINK_EXTRACTOR_VERSION_TS = '2026-10-08T00:00:00Z';

// ─── Entity references ──────────────────────────────────────────

export interface EntityRef {
  /** Display name from the markdown link, e.g. "Alice Chen". */
  name: string;
  /** Resolved page slug, e.g. "people/alice-chen". */
  slug: string;
  /** Top-level directory ("people" | "companies" | etc.). */
  dir: string;
  /**
   * v0.17.0: source id when the link was qualified as `[[source:slug]]`.
   * `null` means unqualified — the caller resolves via local-first fallback
   * at extraction time. Mirrors links.resolution_type:
   *   - sourceId set   → 'qualified'
   *   - sourceId null  → 'unqualified'
   */
  sourceId?: string | null;
  /**
   * Issue #972: set when the ref came from the generic `[[bare-name]]`
   * pass (not gated by DIR_PATTERN). The `slug` field holds the literal
   * wikilink text — callers MUST run it through a SlugResolver's
   * `resolveBasenameMatches` (gated by `link_resolution.global_basename`)
   * before persisting. Untagged refs already match a known entity dir
   * (people/, companies/, etc.) and need no resolution.
   *
   * One ref tagged `needsResolution: true` may resolve to MULTIPLE target
   * slugs when multiple pages share the basename. The caller emits one
   * LinkCandidate per resolved match.
   */
  needsResolution?: boolean;
  /**
   * Number of leading `../` segments on the original markdown link (0 when
   * absent or for engine-slug refs). The match regex strips the `../` run, so
   * this preserves the relative depth for callers that know the linking page's
   * slug (`extractPageLinks`) to resolve the target against the page's own
   * directory. Without it, `[x](../concepts/x.md)` from a nested page resolves
   * as the root-relative `concepts/x` instead of `<page-dir-parent>/concepts/x`
   * — the reason subtree-scoped / nested brains got zero cross-dir edges.
   */
  upLevels?: number;
  /**
   * #3190: set for a same-directory markdown link — `[Name](slug.md)` with
   * no directory segment and no scheme. `slug` holds the target basename
   * (`.md` stripped); the caller (`extractPageLinks`) resolves it against
   * the LINKING page's directory, mirroring the FS path's `resolveSlug`.
   * Pre-fix these refs were silently dropped (pass 1 requires `dir/`),
   * so flat directories and sibling links produced zero DB-path edges.
   */
  sameDir?: boolean;
  /**
   * Char offset of the link match in the page content
   * (stripCodeBlocks and the pass masks are length-preserving, so the
   * offset is valid against the original content). Lets extractPageLinks
   * anchor the context window and the Timeline/See-also role-prior
   * suppression at the ACTUAL link, not at the first occurrence of the
   * display text — a Timeline link whose display name also appears in the
   * bio used to anchor early and take the bio's typing.
   */
  index?: number;
}

/**
 * Issue #972: edge type stamped on graph rows produced by the
 * global-basename wikilink resolution path. Distinct from the verb-
 * inferred types (`mentions`, `works_at`, etc.) so users can audit or
 * prune via `gbrain graph-query <slug> --type wikilink_basename`.
 *
 * All edges from this path also carry `linkSource: 'wikilink-resolved'`
 * (the link-source provenance is the why; this edge type is the what).
 */
export const WIKILINK_BASENAME_LINK_TYPE = 'wikilink_basename';

/** v0.17.0: how a link's target source was pinned at extraction time. */
export type LinkResolutionType = 'qualified' | 'unqualified';

/**
 * Directory prefix whitelist. These are the canonical top-level slug dirs
 * (gbrain-base pack dirs + historical extensions). #2576 (bug 2): this list
 * is NO LONGER a drop-gate for markdown links, bare-slug prose refs, or
 * slash-shaped wikilinks — those now match ANY_DIR_SEGMENT and rely on the
 * downstream page-existence checks that every persist path already runs
 * (resolveCandidateSources in extract.ts, the allSlugs filter in put_page
 * auto-link, and addLinksBatch's INNER JOINs as the final backstop). The
 * whitelist survives only as the typed fast-path for pass-2b wikilinks;
 * non-whitelisted `[[dir/...]]` get equivalent treatment in pass 2c.
 */
const DIR_PATTERN = '(?:people|companies|meetings|concepts|deal|civic|project|projects|source|media|yc|tech|finance|personal|openclaw|entities|reference)';

/**
 * #2576 (bug 2): a plausible top-level slug directory — lowercase alnum
 * with dashes/underscores, digit-leading allowed (`90-people`). Used where
 * the hardcoded DIR_PATTERN whitelist used to silently drop every
 * user-invented directory (`ops/`, `notes/`, custom schema-pack dirs).
 * Candidates matched through this are validated for page existence
 * downstream, so a wider net creates no dead edges — only candidates.
 */
const ANY_DIR_SEGMENT = '[a-z0-9][a-z0-9_-]*';

/**
 * Match `[Name](path)` markdown links pointing at page-shaped paths.
 * Accepts both filesystem-relative format (`[Name](../people/slug.md)`)
 * AND engine-slug format (`[Name](people/slug)`).
 *
 * Captures: name, slug (dir/name, possibly deeper).
 *
 * The regex permits an optional `../` prefix (any number) and an optional
 * `.md` suffix so the same function works for both filesystem and DB content.
 *
 * #2576 (bug 2): the first segment is ANY_DIR_SEGMENT, not the DIR_PATTERN
 * whitelist — `[Pointer](../ops/services/pointer-agent.md)` must produce a
 * candidate for a brain that has an `ops/` directory. Nonexistent targets
 * are dropped by the callers' existence checks, exactly as before.
 */
const ENTITY_REF_RE = new RegExp(
  `\\[([^\\]]+)\\]\\((?:/|(?:\\.\\.\\/)*)(${ANY_DIR_SEGMENT}\\/[^)\\s#]+?)(?:\\.md)?(?:#[^)]*)?\\)`,
  'g',
);

/**
 * Match Obsidian-style `[[path]]` or `[[path|Display Text]]` wikilinks.
 * Captures: slug (dir/...), displayName (optional).
 *
 * Same dir whitelist as ENTITY_REF_RE. Strips trailing `.md`, strips section
 * anchors (`#heading`), skips external URLs. Wiki KBs use this format almost
 * exclusively so missing it leaves the graph empty.
 */
const WIKILINK_RE = new RegExp(
  `\\[\\[(${DIR_PATTERN}\\/[^|\\]#]+?)(?:#[^|\\]]*?)?(?:\\|([^\\]]+?))?\\]\\]`,
  'g',
);

/**
 * v0.17.0: qualified wikilink `[[source-id:dir/slug]]` or
 * `[[source-id:dir/slug|Display Text]]`. The source-id segment pins the
 * target to a specific sources(id) row, overriding the local-first
 * fallback used by unqualified `[[slug]]` references.
 *
 * Captures: sourceId, slug (dir/...), displayName (optional).
 *
 * Matched BEFORE WIKILINK_RE so `[[wiki:topics/ai]]` isn't mis-parsed by
 * the unqualified regex (the source prefix would not satisfy DIR_PATTERN
 * anyway, but the two-pass approach keeps intent crystal-clear).
 */
const QUALIFIED_WIKILINK_RE = new RegExp(
  `\\[\\[([a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?):([^|\\]#\\n[]+?)(?:#[^|\\]]*?)?(?:\\|([^\\]]+?))?\\]\\]`,
  'g',
);

/**
 * Issue #972: generic Obsidian-style wikilink — matches `[[anything]]`
 * with no DIR_PATTERN gate. Wiki/topic/learning pages frequently link
 * via `[[bare-name]]` (`[[Fast-Weigh]]`, `[[2026-05-07-cost-plan]]`,
 * `[[struktura]]`) where the literal text isn't a canonical slug; the
 * resolver is responsible for matching it to the real page via
 * basename uniqueness.
 *
 * Used AFTER QUALIFIED_WIKILINK_RE and WIKILINK_RE pick off their
 * cases — the masked-ranges pass in extractEntityRefs prevents
 * double-emission. Refs from this pass are tagged
 * `needsResolution: true` so callers know to run them through a
 * SlugResolver before the page-existence check.
 *
 * Regex shape is the union of the two existing wikilink regexes,
 * minus the DIR_PATTERN gate. The character class disallows pipe,
 * close-bracket, hash (anchor separator), newline, and open-bracket
 * so we never match across line breaks or capture nested `[[...]]`.
 *
 * Adapted from PR #1233 (rayers).
 */
const WIKILINK_GENERIC_RE = /\[\[([^|\]#\n[]+?)(?:#[^|\]]*?)?(?:\|([^\]]+?))?\]\]/g;

/**
 * Issue #972 (codex [P2]): a markdown link whose LABEL contains a wikilink,
 * e.g. `[see [[acme]]](companies/acme.md)`. Pass-1's ENTITY_REF_RE can't match
 * the nested `]]` so it never spans this; without masking, the generic 2c pass
 * would emit a stray basename ref for the inner `[[acme]]`. Mask the whole
 * span out of the 2c scan so a wikilink inside a markdown label is inert.
 */
const MARKDOWN_LABEL_WIKILINK_RE = /\[[^\]\n]*\[\[[^\]\n]+\]\][^\]\n]*\]\([^)\n]+\)/g;

/**
 * #3190: same-directory markdown link — `[Name](slug.md)` whose target has
 * NO directory segment and NO scheme (`/`, `:` excluded). A trailing
 * `#anchor` is stripped (#4995), as every wikilink regex here already does.
 * #4873: an explicit `./` prefix (`[Name](./slug.md)`, `[Name](./sub/x.md)`)
 * is the same page-dir-relative intent — the FS walker's join() eats it — so
 * the relative arm admits `/` in the tail. The arm takes ANY leading run of
 * `./` / `../` segments (`[Name](../slug.md)`, `[Name](./../slug.md)`): pass 1
 * only claims `../` targets that carry a directory segment, so a parent-dir
 * sibling link had no DB candidate at all while the FS walker's join() linked
 * it — the sweep reconcile then pruned the edge (same class as #4873).
 * Captures: name, dot-prefix run, relative tail, bare tail. The `.md` suffix
 * is REQUIRED (mirrors the FS extractor's mdPattern) so bare parenthetical
 * prose (`[sic](reference)`) never produces a ref. Resolution against the
 * linking page's directory happens in extractPageLinks (this module has no
 * page context here).
 */
const SAME_DIR_MD_RE = /\[([^\]]+)\]\((?:((?:\.{1,2}\/)+)([^):#\s]+?)|([^)/:#\s]+?))\.md(?:#[^)]*)?\)/g;

/**
 * A code-reference found in markdown prose. Created by extractCodeRefs and
 * consumed by importFromFile's tail to build doc↔impl edges (v0.19.0 E1).
 */
export interface CodeRef {
  /** Raw matched path (e.g. 'src/core/sync.ts'). */
  path: string;
  /** Optional line number from 'src/foo.ts:42'. */
  line?: number;
  /** Index in the source string. */
  index: number;
}

// v0.19.0 E1 — markdown guides that cite 'src/core/sync.ts:42' create an
// edge to the code page that imported that file. Regex is anchored against
// the common gbrain repo layout directories so arbitrary prose like
// "in foo/bar.js" doesn't generate false positives.
//
// The extension list is aligned with detectCodeLanguage in chunkers/code.ts.
// Paths NOT matching these extensions are ignored because they wouldn't
// have a code page to edge to anyway.
const CODE_REF_REGEX = /\b((?:src|lib|app|test|tests|scripts|docs|packages|internal|cmd|examples)\/[\w\-./]+\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs|py|rb|go|rs|java|cs|cpp|cc|hpp|c|h|php|swift|kt|scala|lua|ex|exs|elm|ml|dart|zig|sol|sh|bash|css|html|astro|svelte|vue|json|yaml|yml|toml))(?::(\d+))?\b/g;

/**
 * Extract code-path references (e.g. 'src/core/sync.ts:42') from markdown
 * prose. Deduped by path.
 */
/**
 * v0.27.1 (cherry-3): path-proximity auto-link candidate finder for image
 * ingest. Given an image slug like `originals/photos/2026-05-04-foo.jpg`,
 * proposes candidate sibling slugs for an `image_of` edge:
 *   1. `originals/meetings/2026-05-04-foo.md` (parallel directory + same basename)
 *   2. `<parent>/foo.md` (same directory + sibling basename minus extension)
 *
 * Returns slug candidates in priority order. Caller (importImageFile) checks
 * which candidates exist as pages and emits the edge for the first match.
 */
export function imageOfCandidates(imageSlug: string): string[] {
  const lower = imageSlug.toLowerCase();
  const lastSlash = lower.lastIndexOf('/');
  if (lastSlash < 0) return [];
  const dir = lower.slice(0, lastSlash);
  const file = lower.slice(lastSlash + 1);
  // Strip image extension from basename to get a stable identifier.
  const base = file.replace(/\.(png|jpg|jpeg|gif|webp|heic|heif|avif)$/i, '');
  if (!base) return [];

  const out: string[] = [];

  // Heuristic 1: parallel directory swap. originals/photos/X → originals/meetings/X
  const dirParts = dir.split('/');
  const PHOTO_DIRS = new Set(['photos', 'images', 'screenshots', 'media']);
  const SIBLING_DIRS = ['meetings', 'notes', 'daily', 'people', 'companies', 'deals', 'projects'];
  for (let i = 0; i < dirParts.length; i++) {
    if (PHOTO_DIRS.has(dirParts[i])) {
      for (const sib of SIBLING_DIRS) {
        const swapped = [...dirParts];
        swapped[i] = sib;
        out.push(`${swapped.join('/')}/${base}`);
      }
    }
  }

  // Heuristic 2: same directory, basename without ext as a markdown page.
  out.push(`${dir}/${base}`);

  // Deduplicate, drop the imageSlug itself if it accidentally roundtrips.
  const seen = new Set<string>();
  return out.filter(s => {
    if (s === lower) return false;
    if (seen.has(s)) return false;
    seen.add(s);
    return true;
  });
}

export function extractCodeRefs(content: string): CodeRef[] {
  const seen = new Set<string>();
  const refs: CodeRef[] = [];
  let match: RegExpExecArray | null;
  // Using a fresh regex object per call to avoid lastIndex state leaking
  // across invocations.
  const re = new RegExp(CODE_REF_REGEX.source, 'g');
  while ((match = re.exec(content)) !== null) {
    const path = match[1]!;
    if (seen.has(path)) continue;
    seen.add(path);
    const line = match[2] ? parseInt(match[2], 10) : undefined;
    refs.push({ path, line, index: match.index });
  }
  return refs;
}

/**
 * Extract `[Name](path-to-people-or-company)` references from arbitrary content.
 * Both filesystem-relative paths (with `../` and `.md`) and bare engine-style
 * slugs (`people/slug`) are matched. Returns one EntityRef per match (no dedup
 * here; caller dedups). Slugs appearing inside fenced or inline code blocks
 * are excluded — those are typically code samples, not real entity references.
 */
export function extractEntityRefs(content: string): EntityRef[] {
  return entityRefPasses(content).flat();
}

/** extractEntityRefs' refs per pass (markdown, same-dir markdown, qualified, unqualified and generic wikilinks), each pass in text order. */
export function entityRefPasses(content: string): EntityRef[][] {
  const stripped = stripCodeBlocks(content);
  const passes: EntityRef[][] = [[], [], [], [], []];
  let refs = passes[0];
  let match: RegExpExecArray | null;

  // 1. Markdown links: [Name](path)
  //    Markdown links have no source-qualification syntax — they're
  //    always unqualified. Omit sourceId so the shape stays compatible
  //    with pre-v0.17 consumers doing strict equality.
  const markdownRanges: Array<[number, number]> = [];
  const mdPattern = new RegExp(ENTITY_REF_RE.source, ENTITY_REF_RE.flags);
  while ((match = mdPattern.exec(stripped)) !== null) {
    const name = match[1];
    let fullPath = match[2];
    // Obsidian's useMarkdownLinks mode percent-encodes link targets
    // (`[Alice](people/alice%20chen)`). Decode before resolution; a
    // malformed escape keeps the raw text rather than throwing.
    if (fullPath.includes('%')) {
      try { fullPath = decodeURIComponent(fullPath); } catch { /* keep raw */ }
    }
    const slug = fullPath;
    const dir = fullPath.split('/')[0];
    // The regex strips the leading `../` run from `fullPath`; recover its depth
    // from the raw link target so extractPageLinks can resolve relative to the
    // linking page's directory. `[x](path)` has no `](` collision because the
    // capture stops before the first unescaped `)`.
    const rawTarget = match[0].slice(match[0].indexOf('](') + 2, -1);
    const up = rawTarget.match(/^(?:\.\.\/)+/);
    const ref: EntityRef = { name, slug, dir };
    // Only relative links carry depth; absolute / engine-slug refs keep the
    // exact {name, slug, dir} shape (no upLevels key) so equality consumers
    // are unaffected.
    if (up) ref.upLevels = up[0].length / 3;
    ref.index = match.index;
    refs.push(ref);
    markdownRanges.push([match.index, match.index + match[0].length]);
  }

  // 1b. #3190/#4873: same-directory markdown links — `[Name](slug.md)`,
  //     `[Name](./slug.md)`, `[Name](../slug.md)` (no scheme). Pass 1 requires
  //     a `dir/` segment, so sibling and dot-relative links were silently
  //     dropped on the DB path while the FS walker (extractMarkdownLinks →
  //     resolveSlug) linked them. Tagged `sameDir: true`; the `..` depth of
  //     the prefix rides on `upLevels` and extractPageLinks resolves against
  //     the page's dir. A `../dir/x.md` span pass 1 already claimed is skipped
  //     so the two passes never double-emit.
  const sameDirPattern = new RegExp(SAME_DIR_MD_RE.source, SAME_DIR_MD_RE.flags);
  refs = passes[1];
  while ((match = sameDirPattern.exec(stripped)) !== null) {
    const at = match.index;
    if (markdownRanges.some(([s, e]) => at >= s && at < e)) continue;
    const name = match[1];
    let target = match[3] ?? match[4];
    if (target.includes('%')) {
      try { target = decodeURIComponent(target); } catch { /* keep raw */ }
    }
    const ref: EntityRef = { name, slug: target, dir: '', sameDir: true };
    const ups = match[2] ? match[2].split('/').filter(seg => seg === '..').length : 0;
    if (ups) ref.upLevels = ups;
    ref.index = at;
    refs.push(ref);
    markdownRanges.push([at, at + match[0].length]);
  }

  // 2a. v0.17.0 qualified wikilinks: [[source-id:path]] or [[source-id:path|Display]]
  //     Must run BEFORE the unqualified pass or we'd double-emit. We also
  //     mask out the matched spans so pass 2b can't grab them.
  const qualifiedRanges: Array<[number, number]> = [];
  const qualPattern = new RegExp(QUALIFIED_WIKILINK_RE.source, QUALIFIED_WIKILINK_RE.flags);
  refs = passes[2];
  while ((match = qualPattern.exec(stripped)) !== null) {
    const sourceId = match[1];
    let slug = stripEscapedPipeTail(match[2].trim());
    if (!slug) continue;
    if (slug.includes('://')) continue;
    if (slug.endsWith('.md')) slug = slug.slice(0, -3);
    const displayName = (match[3] || slug).trim();
    const dir = slug.split('/')[0];
    refs.push({ name: displayName, slug, dir, sourceId, index: match.index });
    qualifiedRanges.push([match.index, match.index + match[0].length]);
  }

  // 2b. Unqualified Obsidian wikilinks: [[path]] or [[path|Display Text]]
  //     Same shape rule: omit sourceId when unqualified.
  const unqualifiedRanges: Array<[number, number]> = [];
  const unmasked = maskRanges(stripped, qualifiedRanges);
  const wikiPattern = new RegExp(WIKILINK_RE.source, WIKILINK_RE.flags);
  refs = passes[3];
  while ((match = wikiPattern.exec(unmasked)) !== null) {
    let slug = stripEscapedPipeTail(match[1].trim());
    if (!slug) continue;
    if (slug.includes('://')) continue;
    if (slug.endsWith('.md')) slug = slug.slice(0, -3);
    const displayName = (match[2] || slug).trim();
    const dir = slug.split('/')[0];
    refs.push({ name: displayName, slug, dir, index: match.index });
    unqualifiedRanges.push([match.index, match.index + match[0].length]);
  }

  // 2c. Issue #972: generic `[[bare-name]]` wikilinks not gated by
  //     DIR_PATTERN. Wiki/topic/learning content frequently uses these
  //     where the bare text isn't a canonical brain slug. Tagged
  //     `needsResolution: true` so the caller routes them through a
  //     SlugResolver's `resolveBasenameMatches` before persisting.
  //     Mask out 2a/2b ranges so we don't double-emit; skip qualified-
  //     syntax tokens (contain `:`) that would be 2a's job. Issue #972
  //     (codex [P2]): ALSO mask pass-1 markdown-link ranges so a wikilink
  //     inside a markdown label — `[see [[acme]]](companies/acme.md)` —
  //     doesn't spawn a stray generic basename ref from inside the label.
  const labelWikilinkRanges: Array<[number, number]> = [];
  const labelWlPattern = new RegExp(MARKDOWN_LABEL_WIKILINK_RE.source, MARKDOWN_LABEL_WIKILINK_RE.flags);
  while ((match = labelWlPattern.exec(stripped)) !== null) {
    labelWikilinkRanges.push([match.index, match.index + match[0].length]);
  }
  const genericMasked = maskRanges(
    stripped,
    [...markdownRanges, ...qualifiedRanges, ...unqualifiedRanges, ...labelWikilinkRanges],
  );
  const genericPattern = new RegExp(WIKILINK_GENERIC_RE.source, WIKILINK_GENERIC_RE.flags);
  refs = passes[4];
  while ((match = genericPattern.exec(genericMasked)) !== null) {
    let slug = stripEscapedPipeTail(match[1].trim());
    if (!slug) continue;
    if (slug.includes('://')) continue;
    if (slug.includes(':')) continue; // qualified-syntax token; 2a owns these
    if (slug.endsWith('.md')) slug = slug.slice(0, -3);
    const displayName = (match[2] || slug).trim();
    const dir = slug.includes('/') ? slug.split('/')[0] : '';
    refs.push({ name: displayName, slug, dir, needsResolution: true, index: match.index });
  }

  return passes;
}

/**
 * #4062: strip the trailing backslash(es) an escaped pipe leaves on a
 * wikilink target. Inside a markdown table cell the pipe separating the
 * target from its display alias MUST be escaped (`[[dir/slug\|Alias]]`,
 * Obsidian's own table syntax) or it would end the cell. The wikilink
 * slug captures stop at the literal `|`, so the escape backslash lands as
 * the final character of the captured target — a slug shape that can
 * never match a real page. Slugs never legitimately contain backslashes,
 * so stripping the trailing run is lossless. Applied to passes 2a/2b/2c.
 */
function stripEscapedPipeTail(slug: string): string {
  return slug.replace(/\\+$/, '');
}

/**
 * Replace the byte ranges with spaces, preserving offsets. Used by
 * extractEntityRefs to prevent the unqualified wikilink regex from
 * matching inside a qualified wikilink span.
 */
function maskRanges(content: string, ranges: Array<[number, number]>): string {
  if (ranges.length === 0) return content;
  const chars = content.split('');
  for (const [s, e] of ranges) {
    for (let i = s; i < e && i < chars.length; i++) chars[i] = ' ';
  }
  return chars.join('');
}

/**
 * Resolve a markdown ref's target against the LINKING page's directory when the
 * original link was relative (had one or more `../`). Filesystem markdown links
 * are relative to the file that contains them: `[x](../concepts/x.md)` from a
 * page at `wiki/sources/foo` points at `wiki/concepts/x`, not the root-relative
 * `concepts/x`. The match regex discards the `../` run, so `ref.upLevels` carries
 * the depth and this reconstructs the absolute page slug.
 *
 * Backward-compatible: for a page one level below the root (`meetings/m` +
 * `../people/alice` → `people/alice`) the parent walk lands exactly at the root,
 * so the result is identical to the old `../`-stripping behavior. It only
 * diverges — correctly — when the linking page is nested deeper than the `../`
 * count unwinds, i.e. content under a prefix (subtree-scoped sources). An over-
 * long `../` run clamps at the root. Absolute refs (upLevels 0, e.g. engine-slug
 * `people/x` or `[[wikilinks]]`) are returned unchanged.
 */
function resolveRelativeSlug(pageSlug: string, ref: EntityRef): string {
  if (!ref.upLevels || ref.upLevels <= 0) return ref.slug;
  const dirSegs = pageSlug.includes('/') ? pageSlug.split('/').slice(0, -1) : [];
  const keep = Math.max(0, dirSegs.length - ref.upLevels);
  return [...dirSegs.slice(0, keep), ref.slug].join('/');
}

/**
 * A same-directory markdown ref (`sameDir`) resolved against the linking
 * page's directory: `../` / `./../` prefixes (upLevels) and any mid-path
 * `.`/`..` fold the way the FS walker's join() does, slugified through the
 * sync grammar. A run that would climb above the root is a dangling link
 * there too, so it resolves to '' (no candidate).
 */
function resolveSameDirSlug(pageSlug: string, ref: EntityRef): string {
  const segs = pageSlug.includes('/') ? pageSlug.split('/').slice(0, -1) : [];
  for (const seg of ('../'.repeat(ref.upLevels ?? 0) + ref.slug).split('/')) {
    if (seg === '' || seg === '.') continue;
    if (seg !== '..') { segs.push(seg); continue; }
    if (segs.length === 0) return '';
    segs.pop();
  }
  return slugifyPath(segs.join('/'));
}

/**
 * #6983: page-relative slugs for a `.md` markdown link with a directory
 * segment and no `/`, `./` or `../` prefix (`[x](notes/a.md)`), in the FS
 * walker's resolveSlug order: the linking page's directory, then each
 * ancestor, stopping before the root. The first one that is a page wins; the
 * root-relative slug resolveMarkdownLinkSlug returns is the fallback, so
 * wiki-root-relative authoring keeps resolving. Engine-slug links (no `.md`)
 * stay root-relative. Empty for a root-level page or any other link shape.
 */
export function pageRelativeMarkdownSlugs(pageSlug: string, href: string): string[] {
  const target = href.trim().replace(/#.*$/, '');
  if (!/\.md$/i.test(target) || /^[./]/.test(target)) return [];
  const ref = extractEntityRefs(`[link](${href.trim()})`)[0];
  if (!ref || ref.sameDir || ref.upLevels) return [];
  const dirs = pageSlug.split('/').slice(0, -1);
  const slugs: string[] = [];
  for (let keep = dirs.length; keep > 0; keep--) slugs.push(`${dirs.slice(0, keep).join('/')}/${ref.slug}`.toLowerCase());
  return slugs;
}

/** The raw href of the pass-1 markdown link starting at `index` in `content`. */
function markdownHrefAt(content: string, index: number): string | null {
  const re = new RegExp(ENTITY_REF_RE.source, 'y');
  re.lastIndex = index;
  const match = re.exec(content);
  return match ? match[0].slice(match[0].indexOf('](') + 2, -1) : null;
}

/**
 * The page slug a markdown link `href` on page `pageSlug` points at, resolved
 * exactly as extractPageLinks resolves it (page-relative `./` and `../`,
 * root-relative dir paths, `.md` and `#anchor` stripped). Null when the
 * extractor would emit no link for it. A `.md` dir link first tries
 * pageRelativeMarkdownSlugs, which needs page existence; this is its
 * fallback. The writer's link validator calls both, so "the validator
 * accepts it" means "the graph links it".
 */
export function resolveMarkdownLinkSlug(pageSlug: string, href: string): string | null {
  const ref = extractEntityRefs(`[link](${href})`)[0];
  if (!ref) return null;
  const target = ref.sameDir ? resolveSameDirSlug(pageSlug, ref) : resolveRelativeSlug(pageSlug, ref).toLowerCase();
  return target || null;
}

// ─── Link candidates (richer than EntityRef) ────────────────────

export interface LinkCandidate {
  canonicalAttendance?: boolean;
  /**
   * Source page slug for the edge. When omitted, callers default to
   * "the page being written" (operations.ts runAutoLink) or "the page
   * currently being processed" (extract.ts). Explicitly set when
   * frontmatter emits an incoming edge — e.g. a company page's
   * `key_people: [pedro-franceschi]` produces a candidate whose
   * fromSlug is `people/pedro-franceschi`, not the company.
   */
  fromSlug?: string;
  /** Target page slug (no .md, no ../). */
  targetSlug: string;
  targetSourceId?: string;
  /** Inferred relationship type. */
  linkType: string;
  /** Surrounding text (up to ~80 chars) used for inference + storage. */
  context: string;
  /**
   * Provenance (v0.13+). Defaults to 'markdown' on older call sites;
   * frontmatter-derived candidates set 'frontmatter'; user-created edges
   * via explicit API pass 'manual'.
   */
  linkSource?: string;
  /**
   * Origin-page slug. Only populated for link_source='frontmatter' so
   * reconciliation can scope cleanups to edges THIS page's frontmatter
   * created (never touching edges other pages authored).
   */
  originSlug?: string;
  /** Frontmatter field name (e.g. 'key_people'), for debug + unresolved report. */
  originField?: string;
  /**
   * The authored reference this candidate came from (a markdown link or a
   * wikilink in the body). Candidates sharing a `key` are alternative
   * resolutions of one reference; the reference is wanted when none of them
   * resolves (src/core/wanted-links.ts). Bare prose paths carry none.
   */
  authoredRef?: AuthoredRef;
}

export interface ExtractPageLinksOptions {
  globalBasename?: boolean; skipFrontmatter?: boolean; pack?: LinkExtractionPack | null;
  /** Typed relation lines (core/line-grammar.ts); on unless `enabled: false`. */
  lineGrammar?: { enabled?: boolean; allowUndeclaredTypes?: boolean };
  targetType?: (slug: string, sourceId?: string) => string | undefined;
  onResolvedFrontmatterTarget?: (slug: string) => void;
  /** Receives every body-link typing decision with its reasons (explainLinkType, development reports). */
  explain?: (e: LinkTypeExplanation) => void;
  /** The text the page-role priors read (default: the content); a streamed page passes its role phrases (rolePriorPhrases). */
  roleText?: string;
  /** The page's pack-regex budget, shared by the windows of a streamed page. */
  regexBudget?: PageRegexBudget;
  /** extractBodyLinks: extract only references starting in content[start, end), shifting offsets by `offset`. */
  window?: { start: number; end: number; offset: number };
}

/** The authored reference of a wikilink at `idx`: a slug path, or a bare name keyed by its basename. */
function wikilinkAuthoredRef(target: string, idx: number): AuthoredRef | undefined {
  if (target.includes('/')) return { key: `ref:${idx}`, kind: 'slug', target };
  const name = normalizeBasename(target);
  return name ? { key: `ref:${idx}`, kind: 'name', target: name } : undefined;
}

/** One authored body reference, as recorded in `wanted_links` when it does not resolve. */
export interface AuthoredRef {
  key: string;
  kind: 'slug' | 'name';
  target: string;
  targetSourceId?: string;
}

/** One explained typing decision for a body link occurrence (explainLinkType, ExtractPageLinksOptions.explain). */
export interface LinkTypeExplanation extends Omit<LinkTypeTrace, 'type'> {
  target: string;
  /** Offset of the link in the page content (-1 or undefined when unknown). */
  index?: number;
  context: string;
  linkType: string;
  /** A typed relation line's type (core/line-grammar.ts), which wins over everything below. */
  stated: string | null;
  /** The pack link type whose inference rule decided, if any. */
  packRule: string | null;
}

type TypeFor = (ctx: string, targetSlug: string, idx?: number, sourceId?: string, bodyReference?: boolean) => Pick<LinkCandidate, 'linkType' | 'canonicalAttendance'>;

/**
 * The per-occurrence typer of extractPageLinks. Order: a typed relation line (stated type), then the active pack's
 * inference rules, then meeting attendance, then inferLinkType's verb rules and role priors, then unit post-passes.
 */
function makeTypeFor(content: string, pageType: PageType, opts: ExtractPageLinksOptions, attendancePending: Set<number>, attendanceResolved: Set<number>): TypeFor {
  // #3190: pack-aware verb inference. Pack-declared verbs win (page-type
  // bindings, then pack regexes under the shared per-page ReDoS budget);
  // the in-code inferLinkType stays the fall-through for everything the
  // pack doesn't claim — matching the resolution order extract-ner already
  // ships (schema-pack/link-inference.ts header). Pre-fix a user pack's
  // `link_types[].inference.regex` (e.g. parent_of) was silently ignored
  // here and every such edge landed as 'mentions'.
  const pack = opts.pack ?? null;
  const packBudget = pack ? opts.regexBudget ?? new PageRegexBudget() : undefined;
  const packOwnsAttendance = ownsAttendanceInference(pack);
  // Timeline / See-also links never receive the page-role prior — see
  // rolePriorSuppressedRanges (matched on the code-stripped content, so a
  // fenced `## Timeline` never opens a range). idx is the link's position in
  // `content` (stripCodeBlocks and the wikilink mask are length-preserving,
  // so indices line up); idx < 0 / undefined keeps the old behavior.
  const suppressedRanges = rolePriorSuppressedRanges(stripCodeBlocks(content));
  const roleText = opts.roleText ?? roleTriggerText(content);
  const attendanceRanges = attendanceEvidenceRanges(content);
  const statedType = statedRelationTypes(content, { ...opts.lineGrammar, declaredVerbs: pack?.link_types.map(lt => lt.name) });
  return (ctx, targetSlug, idx, sourceId, bodyReference = true) => {
    const explain = opts.explain;
    const decide = (linkType: string, why: Partial<LinkTypeExplanation> = {}, canonicalAttendance?: boolean) => {
      explain?.({ target: targetSlug, index: idx, context: ctx, linkType, stated: null, packRule: null, rule: null, attachment: 'none', suppressed: [], prior: null, unit: null, ...why });
      return canonicalAttendance ? { linkType, canonicalAttendance } : { linkType };
    };
    const stated = bodyReference ? statedType(idx) : undefined; // a typed relation line wins (core/line-grammar.ts)
    if (stated && !(stated === 'attended' && pageType === 'meeting')) return decide(stated, { stated });
    const targetType = opts.targetType?.(targetSlug, sourceId);
    if (pack) {
      const packVerb = inferLinkTypeFromPack(pack, pageType as string, ctx, packBudget, targetType);
      if (packVerb && (packOwnsAttendance || packVerb !== 'attended' || pageType !== 'meeting')) {
        if (packVerb === 'attended' && pageType === 'meeting'
          && (opts.targetType ? targetType !== 'person' : !targetSlug.startsWith('people/'))) return decide('mentions', { packRule: packVerb });
        return decide(packVerb, { packRule: packVerb });
      }
    }
    if (pageType === 'meeting') {
      if (!bodyReference) return decide('mentions', { rule: 'page.meeting' });
      if (packOwnsAttendance && pack?.link_types.some(lt => lt.name === 'attended' && (lt.inference?.page_type || lt.inference?.target_type))) return decide('mentions', { rule: 'page.meeting', packRule: 'attended' });
      if (idx !== undefined && hasAttendanceEvidence(attendanceRanges, idx)) {
        attendancePending.add(idx);
        if (!opts.targetType || targetType !== undefined) attendanceResolved.add(idx);
      }
      if ((opts.targetType ? targetType === 'person' : targetSlug.startsWith('people/'))
        && idx !== undefined && hasAttendanceEvidence(attendanceRanges, idx)) {
        return decide('attended', { rule: 'page.meeting.attendance' }, true);
      }
      return decide('mentions', { rule: 'page.meeting' });
    }
    const suppressPrior = idx !== undefined && idx >= 0 && inSuppressedRange(suppressedRanges, idx);
    const trace = traceLinkType(pageType, ctx, suppressPrior ? undefined : roleText, targetSlug,
      opts.targetType ? targetType ?? null : undefined, bodyReference && idx !== undefined && idx >= 0 ? excerptAnchor(content, idx, 240) : undefined, roleText, !!explain);
    const { type, ...why } = trace;
    if (pack?.link_types.some(lt => lt.name === type && (lt.inference?.page_type || lt.inference?.target_type))) return decide('mentions', { ...why, packRule: type });
    return decide(type, why);
  };
}

/**
 * Result of extractPageLinks. `candidates` includes markdown refs + bare
 * slug refs + frontmatter-derived edges (v0.13). `unresolved` lists
 * frontmatter names that did not resolve to any page — surfaced in the
 * put_page auto_links response and the extract summary so users know
 * where the graph has holes.
 */
export interface PageLinksResult {
  candidates: LinkCandidate[];
  unresolved: UnresolvedFrontmatterRef[];
  attendanceComplete: boolean;
}

/**
 * Extract all link candidates from a page.
 *
 * Sources:
 *   1. Markdown entity refs in compiled_truth + timeline (extractEntityRefs).
 *   2. Bare slug references in text (people/slug, companies/slug).
 *   3. Frontmatter fields → typed graph edges (v0.13: company, investors,
 *      attendees, key_people, etc.). See FRONTMATTER_LINK_MAP.
 *
 * ASYNC (v0.13): frontmatter extraction resolves display names to slugs
 * via the supplied resolver, which may hit the DB. Pre-v0.13 callers
 * that don't care about frontmatter can pass a resolver that always
 * returns null; only markdown/bare-slug candidates are emitted.
 *
 * Within-page dedup: multiple mentions of the same (fromSlug, targetSlug,
 * linkType) tuple collapse to one candidate. First occurrence wins.
 */
export async function extractPageLinks(
  slug: string,
  content: string,
  frontmatter: Record<string, unknown>,
  pageType: PageType,
  resolver: SlugResolver,
  opts: ExtractPageLinksOptions = {},
): Promise<PageLinksResult> {
  const body = await extractBodyLinks(slug, content, pageType, resolver, opts);
  const fm = await frontmatterLinks(slug, frontmatter, pageType, resolver, opts);
  return { candidates: dedupeCandidates([...body.links.map(link => link.candidate), ...fm.candidates]), unresolved: fm.unresolved,
    attendanceComplete: body.attendanceComplete && fm.attendanceComplete };
}

/** A body reference's candidate, with its extraction pass (entityRefPasses' five, then 5 for bare paths) and its offset in the page. */
export interface BodyLinkCandidate { pass: number; index: number; candidate: LinkCandidate }

/**
 * extractPageLinks' body candidates (markdown refs, wikilinks, bare slug paths) in extraction order, undeduplicated.
 * With `opts.window`, only references starting inside `content[start, end)` are extracted, and their offsets
 * (`index`, authored-ref keys) are shifted by `offset` into the page's coordinates.
 */
export async function extractBodyLinks(slug: string, content: string, pageType: PageType, resolver: SlugResolver,
  opts: ExtractPageLinksOptions = {}): Promise<{ links: BodyLinkCandidate[]; attendanceComplete: boolean }> {
  // The links fence is projected as its own edges (links-fence-projection.ts); its cells are not body references.
  content = maskLinksFence(content);
  const links: BodyLinkCandidate[] = [];
  const shift = opts.window?.offset ?? 0;
  const inWindow = (idx: number) => !opts.window || (idx >= opts.window.start && idx < opts.window.end);
  let pass = 0;
  const candidates = { push: (candidate: LinkCandidate, idx: number) => links.push({ pass, index: idx + shift, candidate }) };

  const attendancePending = new Set<number>();
  const attendanceResolved = new Set<number>();
  const attendanceAmbiguous = new Set<number>();
  const typeFor = makeTypeFor(content, pageType, opts, attendancePending, attendanceResolved);

  // 1. Markdown entity refs.
  for (const [refPass, refs] of entityRefPasses(content).entries()) for (const ref of refs) {
    pass = refPass;
    if (!inWindow(ref.index!)) continue;
    // #3190: same-directory markdown link — resolve against THIS page's
    // directory (the FS path's resolveSlug does exactly this via
    // join(fileDir, target)). Slugified through the sync grammar so
    // `[Alice](Alice%20Chen.md)` reaches `people/alice-chen`. Downstream
    // existence checks drop targets that aren't pages.
    if (ref.sameDir) {
      const target = resolveSameDirSlug(slug, ref);
      if (target && target !== slug) {
        const idx = ref.index ?? content.indexOf(ref.name);
        const context = idx >= 0 ? excerpt(content, idx, 240) : ref.name;
        candidates.push({
          targetSlug: target,
          ...typeFor(context, target, idx),
          context,
          linkSource: 'markdown',
          authoredRef: { key: `ref:${idx + shift}`, kind: 'slug', target },
        }, idx);
      }
      continue;
    }
    // Issue #972: refs from the generic `[[bare-name]]` pass carry the
    // literal wikilink text, not a real page slug. When global_basename
    // mode is on AND the resolver implements basename lookup, resolve
    // to every matching page and emit one candidate per match. When the
    // flag is off (default), drop silently — back-compat with the
    // pre-v0.40.8.2 behavior of dropping bare wikilinks outside
    // DIR_PATTERN.
    if (ref.needsResolution) {
      const slashIdx = ref.slug.lastIndexOf('/');
      // #2576 (bug 2): a slash-shaped wikilink outside DIR_PATTERN
      // (`[[ops/services/pointer-agent]]`) gets the SAME treatment a
      // whitelisted dir gets from pass 2b — a direct, verb-typed candidate
      // for the literal path, emitted regardless of the global_basename
      // flag. Downstream existence checks (resolveCandidateSources /
      // put_page's allSlugs filter / addLinksBatch's INNER JOINs) drop it
      // when no such page exists, exactly as they do for 2b candidates.
      // Pre-fix these refs were silently dropped (flag off) or demoted to
      // untyped wikilink_basename edges (flag on).
      if (slashIdx !== -1 && ref.slug !== slug) {
        const litIdx = ref.index ?? content.indexOf(ref.slug);
        const litContext = litIdx >= 0 ? excerpt(content, litIdx, 240) : ref.name;
        candidates.push({
          targetSlug: ref.slug,
          ...typeFor(litContext, ref.slug, litIdx),
          context: litContext,
          linkSource: 'markdown',
          authoredRef: { key: `ref:${litIdx + shift}`, kind: 'slug', target: ref.slug },
        }, litIdx);
      }
      // #4062: a bare `[[name]]` (no slash) gets a direct verb-typed
      // candidate for its root-exact slugified form, emitted regardless of
      // the global_basename flag — mirroring the FS path, where resolveSlug's
      // ancestor walk resolves `[[x]]` to a root page `x` before the
      // basename fallback ever runs. Pre-fix the DB path dropped these
      // entirely flag-off (0 candidates) while the FS path linked them.
      // Downstream existence checks (resolveCandidateSources / put_page's
      // allSlugs filter / addLinksBatch's INNER JOINs) drop the candidate
      // when no root page exists, exactly as for slash-shaped refs above.
      // #4855 twin: both slug grammars — sync's slugifyPath keeps stroke
      // letters (`đuc-example`), normalizeBasename folds them (`duc-example`)
      // — so `[[Đức Example]]` reaches whichever root page exists with the
      // flag off. Exact slugs only; downstream existence checks drop the miss.
      const bareDirect = new Set<string>();
      if (slashIdx === -1) {
        for (const form of [slugifyPath(ref.slug), normalizeBasename(ref.slug)]) {
          if (form && form !== slug) bareDirect.add(form);
        }
      }
      // Issue #972 (codex): resolve by the wikilink TARGET (ref.slug — the
      // text inside `[[...]]` before any `|`), NOT the display alias
      // (ref.name = match[2]). `[[struktura|the project]]` must resolve
      // `struktura`, not "the project". The display text is for context only.
      //
      // Issue #1964: a dir-qualified wikilink (`[[llm-wiki/entities/AI 3.0]]`)
      // carries a raw Obsidian path while page slugs are sync-slugified
      // (`llm-wiki/entities/ai-3.0`). Slugify the path the same way sync does,
      // then match by exact slug or path-suffix (wiki-root-relative authoring).
      // This runs regardless of global_basename — it's dir-qualified, so the
      // cross-dir false-positive risk the flag guards against doesn't apply.
      // Mirrors the FS path's resolveSlug ancestor walk. Bare `[[name]]`
      // wikilinks still require the global_basename flag.
      // The EXACT raw literal is excluded — the direct typed candidate
      // above already covers it (#2576), so keeping it would double-emit.
      let matches: string[] = [];
      const slugified = ref.slug.includes('/') ? slugifyPath(ref.slug) : '';
      if (resolver.resolveBasenameMatches && slugified.includes('/')) {
        const tail = slugified.slice(slugified.lastIndexOf('/') + 1);
        matches = (await resolver.resolveBasenameMatches(tail))
          .filter(m => m !== ref.slug && (m === slugified || m.endsWith(`/${slugified}`)));
      } else if (resolver.resolveBasenameMatches && opts.globalBasename) {
        // #4062: exclude the root-exact slugified form — the direct typed
        // candidate above already covers it (same rule the dir-qualified
        // branch applies to its raw literal). Keeping it would double-emit.
        matches = (await resolver.resolveBasenameMatches(ref.slug))
          .filter(m => !bareDirect.has(m));
      }
      matches = matches.filter(matched => matched !== slug);
      const idx = ref.index ?? content.indexOf(ref.slug);
      const context = idx >= 0 ? excerpt(content, idx, 240) : ref.name;
      const targets = [...new Set([...bareDirect, ...matches])];
      const personTargets = targets.filter(target => opts.targetType
        ? opts.targetType(target) === 'person' : target.startsWith('people/'));
      const uniquePerson = personTargets.length === 1;
      if (pageType === 'meeting' && opts.targetType && !uniquePerson
        && targets.filter(target => opts.targetType!(target) !== undefined).length > 1) attendanceAmbiguous.add(idx);
      const authoredRef = wikilinkAuthoredRef(ref.slug, idx + shift);
      for (const target of bareDirect) {
        const inferred = typeFor(context, target, idx);
        candidates.push({ targetSlug: target,
          ...(inferred.canonicalAttendance && !uniquePerson ? { linkType: 'mentions' } : inferred),
          context, linkSource: 'markdown', ...(authoredRef ? { authoredRef } : {}) }, idx);
      }
      for (const matched of matches) {
        const inferred = typeFor(context, matched, idx);
        candidates.push({
          targetSlug: matched,
          ...(inferred.canonicalAttendance && uniquePerson ? inferred : { linkType: WIKILINK_BASENAME_LINK_TYPE }),
          context,
          linkSource: 'wikilink-resolved',
          ...(authoredRef ? { authoredRef } : {}),
        }, idx);
      }
      continue;
    }
    // Anchor at the ref's true match offset when the pass
    // recorded one — first-occurrence-of-display-text anchoring let a
    // Timeline link inherit the bio's context (and its verb typing).
    const idx = ref.index ?? content.indexOf(ref.name);
    // Wider context window (240 chars vs original 80) catches verbs that
    // appear at sentence-or-paragraph distance from the slug — common in
    // narrative prose where a partner's investment verbs appear once and
    // then portfolio companies are listed in subsequent sentences.
    const context = idx >= 0 ? excerpt(content, idx, 240) : ref.name;
    // Relative markdown links resolve against THIS page's directory (fixes
    // cross-dir edges for nested / subtree-scoped content); absolute refs pass
    // through unchanged. #4995: lowercased (pass-1 markdown + 2a/2b wikilink
    // refs) — validateSlug stores every slug lowercase on both engines, so a
    // mixed-case candidate could never resolve. NOT slugifyPath: it strips
    // characters validateSlug permits and would mangle a legit put_page slug.
    let targetSlug = resolveRelativeSlug(slug, ref).toLowerCase();
    // #6983: a `.md` dir link resolves against this page's directory first,
    // like the FS walker; the root-relative slug stays the fallback.
    const href = refPass === 0 && resolver.resolveBasenameMatches ? markdownHrefAt(content, idx) : null;
    const pageRelative = href ? pageRelativeMarkdownSlugs(slug, href) : [];
    if (pageRelative.length > 0) {
      const existing = new Set(await resolver.resolveBasenameMatches!(ref.slug.slice(ref.slug.lastIndexOf('/') + 1)));
      targetSlug = pageRelative.find(s => existing.has(s)) ?? targetSlug;
    }
    candidates.push({
      targetSlug,
      targetSourceId: ref.sourceId ?? undefined,
      ...typeFor(context, targetSlug, idx, ref.sourceId ?? undefined),
      context,
      linkSource: 'markdown',
      authoredRef: { key: `ref:${idx + shift}`, kind: 'slug', target: targetSlug, ...(ref.sourceId ? { targetSourceId: ref.sourceId } : {}) },
    }, idx);
  }

  // 2. Bare slug references (e.g. "see people/alice-chen for context").
  // #2576 (bug 2): any dir-shaped path, not just the DIR_PATTERN whitelist —
  // `see ops/services/pointer-agent` must produce a candidate. Prose noise
  // that happens to look like a path (`on/off`, `com/foo/bar` inside a URL)
  // is dropped by the callers' page-existence checks, never persisted.
  // Code blocks are stripped first — slugs in code samples are not real refs.
  // Wikilink spans are masked too (equal-length blanks, so match indices stay
  // valid for excerpt()): the wikilink pass above owns `[[...]]` interiors,
  // and without the mask a dir-qualified wikilink like
  // `[[llm-wiki/entities/AI 3.0]]` leaves its lowercase prefix
  // `llm-wiki/entities` as a bare-path match — a spurious edge to the parent
  // page whenever that page exists.
  const strippedContent = stripCodeBlocks(content)
    .replace(/\[\[[^\]]*\]\]/g, (s) => ' '.repeat(s.length));
  const bareRe = new RegExp(
    `\\b(${ANY_DIR_SEGMENT}\\/[a-z0-9][a-z0-9/-]*[a-z0-9])\\b`,
    'g',
  );
  let m: RegExpExecArray | null;
  pass = 5;
  while ((m = bareRe.exec(strippedContent)) !== null) {
    if (!inWindow(m.index)) continue;
    // Skip matches that are part of a markdown link (already handled above).
    const charBefore = m.index > 0 ? strippedContent[m.index - 1] : '';
    if (charBefore === '/' || charBefore === '(') continue;
    // #2576: never emit a self-loop for a page mentioning its own slug.
    if (m[1] === slug) continue;
    const context = excerpt(strippedContent, m.index, 240);
    const inferred = typeFor(context, m[1], m.index, undefined, false);
    candidates.push({
      targetSlug: m[1],
      ...(inferred.canonicalAttendance ? { linkType: 'mentions' } : inferred),
      context,
      linkSource: 'markdown',
    }, m.index);
  }
  return { links, attendanceComplete: [...attendancePending].every(index => attendanceResolved.has(index) && !attendanceAmbiguous.has(index)) };
}

/** extractPageLinks' frontmatter-derived candidates; none with `skipFrontmatter`. */
export async function frontmatterLinks(slug: string, frontmatter: Record<string, unknown>, pageType: PageType, resolver: SlugResolver,
  opts: ExtractPageLinksOptions = {}): Promise<Pick<PageLinksResult, 'candidates' | 'unresolved' | 'attendanceComplete'>> {
  // 3. Frontmatter-derived edges (v0.13). Includes the legacy `source:`
  // field along with the full field map. Caller can suppress via
  // `opts.skipFrontmatter` — used by `extractLinksFromDB` to keep
  // `--include-frontmatter` off semantics while still passing a real
  // resolver (needed for `resolveBasenameMatches` in global-basename
  // mode). Pre-issue-#972 this gating lived in the caller via a
  // synthetic `nullResolver`; that pattern broke once the bare-wikilink
  // path needed `resolveBasenameMatches` on the real resolver.
  if (opts.skipFrontmatter) return { candidates: [], unresolved: [], attendanceComplete: true };
  const fm = await extractFrontmatterLinks(slug, pageType, frontmatter, resolver, opts.globalBasename, opts.pack ?? null, opts.targetType,
    opts.onResolvedFrontmatterTarget);
  return { candidates: fm.candidates, unresolved: fm.unresolved, attendanceComplete: fm.attendanceComplete };
}

/** The within-page dedup key: candidates sharing it collapse to the first. */
export function candidateKey(c: LinkCandidate): string {
  return `${c.fromSlug ?? ''}\u0000${c.targetSourceId ?? ''}\u0000${c.targetSlug}\u0000${c.linkType}\u0000${c.linkSource ?? ''}\u0000${c.canonicalAttendance ?? false}`;
}

export function dedupeCandidates(candidates: LinkCandidate[]): LinkCandidate[] {
  // Within-page dedup: same (fromSlug, targetSlug, linkType, linkSource)
  // collapses to one entry. First occurrence wins.
  // Issue #972 (codex P2d, decided): a qualified `[[companies/acme]]` (typed
  // markdown edge) and a bare `[[acme]]` (wikilink-resolved edge) to the SAME
  // target are KEPT as separate rows — they carry different provenance
  // (link_source) and link_type, and the audit trail (which kind of reference
  // created the edge) is worth more than collapsing them. graph-query callers
  // that want a unique target set dedup on to_slug themselves.
  const seen = new Set<string>();
  const result: LinkCandidate[] = [];
  for (const c of candidates) {
    const key = candidateKey(c);
    if (seen.has(key)) continue;
    seen.add(key);
    result.push(c);
  }
  return result;
}

export function resolvedLinkCandidate(candidate: LinkCandidate, originSlug: string, originSourceId: string,
  resolved: { fromSlug: string; fromSourceId: string; toSourceId: string }): LinkBatchInput {
  const row = {
    from_slug: resolved.fromSlug, to_slug: candidate.targetSlug,
    from_source_id: resolved.fromSourceId, to_source_id: resolved.toSourceId,
    link_type: candidate.linkType, context: candidate.context, link_source: candidate.linkSource,
    origin_slug: candidate.canonicalAttendance ? originSlug : candidate.originSlug,
    origin_source_id: originSourceId, origin_field: candidate.originField, resolution_type: candidate.targetSourceId ? 'qualified' as const : 'unqualified' as const,
  };
  return candidate.canonicalAttendance ? orientCanonicalAttendance(row) : row;
}

export function orientCanonicalAttendance<T extends LinkBatchInput>(row: T): T {
  return { ...row, from_slug: row.to_slug, to_slug: row.from_slug,
    from_source_id: row.to_source_id, to_source_id: row.from_source_id,
    origin_slug: row.from_slug, origin_source_id: row.from_source_id };
}

/**
 * Extract markdown links to .md files (relative paths only).
 *
 * Handles two syntaxes:
 *   1. Standard markdown:  [text](relative/path.md)
 *   2. Wikilinks:          [[relative/path]] or [[relative/path|Display Text]]
 *
 * Both are resolved relative to the file that contains them. External URLs
 * (containing ://) are always skipped. Section anchors (#heading) are stripped
 * from both (#4995); for wikilinks, the .md suffix is added if absent.
 */
export function extractMarkdownLinks(content: string, positions = false): { name: string; relTarget: string; index?: number }[] {
  const results: { name: string; relTarget: string; index?: number }[] = [];

  const mdPattern = /\[([^\]]+)\]\(([^)#]+\.md)(?:#[^)]*)?\)/g;
  let match;
  while ((match = mdPattern.exec(content)) !== null) {
    let target = match[2];
    if (target.includes('://')) continue;
    // Obsidian's useMarkdownLinks mode percent-encodes link targets
    // (`[Alice](People/Alice%20Chen.md)`). Decode before resolution; a
    // malformed escape keeps the raw text rather than throwing.
    if (target.includes('%')) {
      try { target = decodeURIComponent(target); } catch { /* keep raw */ }
    }
    results.push({ name: match[1], relTarget: target, ...(positions ? { index: match.index } : {}) });
  }

  const wikiPattern = /\[\[([^|\]]+?)(?:\|[^\]]*?)?\]\]/g;
  while ((match = wikiPattern.exec(content)) !== null) {
    const rawPath = match[1].trim();
    if (rawPath.includes('://')) continue;
    const hashIdx = rawPath.indexOf('#');
    const pagePath = hashIdx >= 0 ? rawPath.slice(0, hashIdx) : rawPath;
    if (!pagePath) continue;
    const relTarget = pagePath.endsWith('.md') ? pagePath : pagePath + '.md';
    const pipeIdx = match[0].indexOf('|');
    const displayName = pipeIdx >= 0 ? match[0].slice(pipeIdx + 1, -2).trim() : rawPath;
    results.push({ name: displayName, relTarget, ...(positions ? { index: match.index } : {}) });
  }

  return results;
}

export function attendanceEvidenceRanges(content: string): Array<[number, number]> {
  const comments: Array<[number, number]> = [];
  let visible = '', afterComment = 0;
  const masked = stripCodeBlocks(content, { onHtmlComment(start, end) {
    comments.push([start, end]);
    visible += content.slice(afterComment, start) + content.slice(start, end).replace(/[^\r\n]/g, ' ');
    afterComment = end;
  } });
  visible += content.slice(afterComment);
  const lines: Array<{ text: string; start: number; end: number }> = [];
  let start = 0;
  for (const text of visible.split('\n')) {
    lines.push({ text, start, end: start + text.length });
    start += text.length + 1;
  }
  const list = (text: string) => {
    let count = 0;
    const rest = text.replace(/\[\[[^\[\]\n]+\]\]|\[[^\[\]\n]+\]\([^\s()\n]+\)/g, () => { count++; return ''; });
    return count > 0 && /^[\s,;.&]*$/.test(rest);
  };
  const ranges: Array<[number, number]> = [];
  let section: { valid: boolean; entries: Array<[number, number]> } | undefined;
  const finishSection = () => {
    if (section?.valid) ranges.push(...section.entries);
    section = undefined;
  };
  let frontmatter = lines[0]?.text.trim() === '---';
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];
    if (frontmatter) {
      if (i > 0 && /^(?:---|\.\.\.)\s*$/.test(line.text)) frontmatter = false;
      continue;
    }
    if (!masked.slice(line.start, line.end).trim()) {
      if (section && line.text.trim()) section.valid = false;
      continue;
    }
    if (/^#{1,2}[ \t]/.test(line.text)) finishSection();
    if (/^##[ \t]+(?:Attendees|Participants)[ \t]*\r?$/i.test(line.text)) {
      section = { valid: true, entries: [] };
      continue;
    }
    if (section) {
      if (!line.text.trim()) continue;
      if (/^(?: {4}|\t)/.test(line.text)
        || !list(line.text.replace(/^[ \t]*[-*+][ \t]+/, ''))) section.valid = false;
      section.entries.push([line.start, line.end]);
      continue;
    }
    const inline = /^(?:(?:Attendees|Participants):|\*\*(?:Attendees|Participants):\*\*|\*\*(?:Attendees|Participants)\*\*:)[ \t]*(.*)$/i.exec(line.text);
    if (inline && list(inline[1])) ranges.push([line.start, line.end]);
  }
  finishSection();
  const admitted: Array<[number, number]> = [];
  let commentIndex = 0;
  for (const [start, end] of ranges) {
    let cursor = start;
    while (commentIndex < comments.length && comments[commentIndex][1] <= start) commentIndex++;
    for (let i = commentIndex; i < comments.length && comments[i][0] < end; i++) {
      if (comments[i][0] > cursor) admitted.push([cursor, comments[i][0]]);
      cursor = Math.max(cursor, comments[i][1]);
    }
    if (cursor < end) admitted.push([cursor, end]);
  }
  return admitted;
}

export function hasAttendanceEvidence(ranges: ReadonlyArray<readonly [number, number]>, index: number): boolean {
  let low = 0;
  let high = ranges.length - 1;
  while (low <= high) {
    const middle = Math.floor((low + high) / 2);
    const [start, end] = ranges[middle];
    if (index < start) high = middle - 1;
    else if (index >= end) low = middle + 1;
    else return true;
  }
  return false;
}

/**
 * Excerpt a window of `width` chars around `idx`, collapsed to one line.
 *
 * The window is sliced by raw UTF-16 index, so a boundary can land inside a
 * surrogate pair (any non-BMP char — emoji, math alphanumerics, non-BMP CJK)
 * and leave a lone surrogate half. That lone half flows into the link `context`
 * field and, when the batch is serialized for the `jsonb_to_recordset` insert,
 * makes Postgres reject the WHOLE batch on the `::jsonb` cast — aborting the
 * entire `extract --stale` run (#2011). `ensureWellFormed` replaces any orphaned
 * half with U+FFFD before the slice escapes this function.
 */
/** Where `idx` lands inside `excerpt(s, idx, width)`: the link's own position, not the first mention of its target. */
function excerptAnchor(s: string, idx: number, width: number): number {
  return s.slice(Math.max(0, idx - Math.floor(width / 2)), idx).replace(/\s+/g, ' ').trimStart().length;
}

function excerpt(s: string, idx: number, width: number): string {
  const half = Math.floor(width / 2);
  const start = Math.max(0, idx - half);
  const end = Math.min(s.length, idx + half);
  return ensureWellFormed(s.slice(start, end)).replace(/\s+/g, ' ').trim();
}

// ─── Relationship type inference (deterministic, zero LLM) ──────

// ─── Type-inference patterns ────────────────────────────────────
//
// Calibrated against the BrainBench rich-prose corpus (240 pages of
// LLM-generated narrative). The templated 80-page benchmark hit 94.4% type
// accuracy, but rich prose dropped to 70.7% before this round of tuning —
// LLMs use far more verb forms than the original regexes covered.
//
// Key issues fixed:
//   - INVESTED_RE missed "led the seed", "led the Series A", "early investor",
//     "invests in" (present), "investing in" (gerund), "portfolio company".
//   - ADVISES_RE matched generic "board member" / "sits on the board" which
//     also describes investors holding board seats. Tightened to require
//     explicit "advisor"/"advise" rooting.

// Employment context: position + at/of, or explicit work verbs.
//
// v0.10.5 additions (drive works_at 58% → >85% on rich prose):
//   - Role-prefixed engineer patterns: "senior engineer at", "staff engineer at",
//     "principal engineer at", "lead engineer at". Current "engineer at" only
//     hits if the word "engineer" is immediately adjacent; prose often uses
//     rank-qualified forms.
//   - Generic role patterns: "backend engineer at", "frontend engineer at",
//     "ML engineer at", "data engineer at", "full-stack engineer at".
//   - Broader role verbs: "manages engineering at", "running product at",
//     "leads the [team] at", "heads up engineering at".
//   - Possessive time: "his time at", "her time at", "their time at", "my time at".
//   - Role noun forms: "role at", "tenure as", "stint as", "position at".
//   - Promoted/staff-engineer forms: "promoted to (staff|senior|principal) engineer at".
const WORKS_AT_RE = /\b(?:joined\b[^.\n]{0,80}?\bas (?:an? |the )?(?:senior |staff |principal |lead |founding |chief )?(?:engineer|developer|designer|product manager|engineering manager|manager|director|head of [a-z]+|scientist|researcher|analyst|employee|operator|cto|ceo|coo|cfo|cmo|vp)|CEO of|CTO of|COO of|CFO of|CMO of|CRO of|VP at|VP of|VPs? Engineering|VPs? Product|works at|worked at|working at|employed by|employed at|joined as|joined the team|engineer at|engineer for|director at|director of|head of|heads up .{0,20} at|leads engineering|leads product|leads the .{0,20} (?:team|org) at|manages engineering at|manages product at|running (?:engineering|product|design) at|currently at|previously at|previously worked at|spent .* (?:years|months) at|stint at|stint as|tenure at|tenure as|role at|position at|(?:senior|staff|principal|lead|backend|frontend|full-?stack|ML|data|security) engineer at|promoted to (?:senior|staff|principal|lead) .{0,20} at|(?:his|her|their|my) time at)\b/i;

// Investment context. Order patterns from most-specific to least to keep
// regex efficient. Includes funding-round verbs ("led the seed", "led X's
// Series A"), narrative verbs ("invests in", "investing in"), historical
// ("early investor in", "first check"), and portfolio framing ("portfolio
// company", "portfolio includes").
const INVESTED_RE = /\b(?:invested in|invests in|investing in|invest in|investment in|investments in|backed by|funding from|funded by|raised from|led the (?:seed|Series|round|investment|round)|led .{0,30}(?:Series [A-Z]|seed|round|investment)|participated in (?:the )?(?:seed|Series|round)|wrote (?:a |the )?check|first check|early investor|portfolio (?:company|includes)|term sheet for)\b/i;
// "board seat at/in/on": its own rule (same verb, same precedence) so U3 can require an investor prior for it.
const BOARD_SEAT_RE = /\bboard seat (?:at|in|on)\b/i;

// Founded patterns. Includes the noun-form "founder of" / "founders include"
// because that's how real prose identifies founders ("Carol Wilson is the
// founder of Anchor"). Diagnosed via BrainBench rich-corpus misses.
const FOUNDED_RE = /\b(?:founded|co-?founded|started the company|incorporated|founder of|founders? (?:include|are)|the founder|is a co-?founder|is one of the founders)\b/i;

// Advise context: must be rooted in "advisor"/"advise" (investors also sit on
// boards). Keep "board advisor" / "advisory board" but drop generic "board
// member" / "sits on the board" which over-matches.
//
// v0.10.5 additions (drive advises 41% → >85% on rich prose):
//   - Advisory capacity phrasings: "in an advisory capacity", "advisory engagement",
//     "advisory partnership", "advisory contract", "advisory relationship".
//   - "as an advisor" form: joined/serves/brought on "as an advisor" / "as a
//     security advisor" / "as a technical advisor" / "as an industry advisor".
//   - "consults for / consulting role": advisor-adjacent verbs that appear in
//     narratives where the direct "advises" verb isn't used.
//   - Advisor-qualified: "strategic advisor to|at", "technical advisor to|at",
//     "security advisor to|at", "product advisor to|at", "industry advisor".
const ADVISES_RE = /\b(?:advises|advised|advisor (?:to|at|for|of)|advisory (?:board|role|position|capacity|engagement|partnership|contract|relationship|work)|board advisor|on .{0,20} advisory board|joined .{0,20} advisory board|in an? advisory (?:capacity|role|position)|as an? (?:advisor|security advisor|technical advisor|strategic advisor|industry advisor|product advisor|board advisor|senior advisor)|(?:strategic|technical|security|product|industry|senior|board) advisor (?:to|at|for|of)|consults for|consulting role (?:at|with))\b/i;

// Chinese link type patterns for CJK entity mentions.
// NOTE: These patterns are Chinese-only (zh). Japanese and Korean link
// type extraction is not yet implemented. Entity NAME extraction in
// by-mention.ts covers all three scripts (CJK = Chinese/Japanese/Korean)
// via Unicode-aware tokenization.
const ZH_FOUNDED_RE = /(?:创立|创办|成立|创建|建立|开创|发起)(?:了|的)/;
const ZH_INVESTED_RE = /(?:投资|入股|融资|注资|参股)(?:了|的|了?于)/;
const ZH_ADVISES_RE = /(?:顾问|咨询|指导)(?:了|的)?/;
const ZH_WORKS_AT_RE = /(?:任职|就职|担任|供职|在.{0,10}(?:工作|上班|负责))(?:于|在|的)?/;
const ZH_CITED_RE = /(?:引用|援引|提到|提及|转述|摘录)(?:了|的|自)?/;

// Page-role detection: if the source page describes a partner/investor at
// page level, that's a strong prior for outbound company refs being
// invested_in even when per-edge context lacks explicit investment verbs.
const PARTNER_ROLE_RE = /\b(?:partner at|partner of|venture partner|VC partner|invested early|investor at|investor in|portfolio|venture capital|early-stage investor|seed investor|fund [A-Z]|invests across|backs companies)\b/i;

// Advisor role prior: fires when the page-level description indicates the
// person IS an advisor (not just mentions advising). Broadened in v0.10.5
// from "full-time/professional/advises multiple" to catch any page that
// self-identifies the subject as an advisor.
const ADVISOR_ROLE_RE = /\b(?:full-time advisor|professional advisor|advises (?:multiple|several|various)|is an? (?:advisor|security advisor|technical advisor|strategic advisor|industry advisor|product advisor|senior advisor)|took on advisory roles|(?:her|his|their) advisory (?:work|role|engagement|portfolio)|serves as (?:an )?advisor)\b/i;

// Employee role prior (new in v0.10.5): fires when the page-level description
// indicates the person IS an employee (senior/staff/lead engineer, director,
// head, etc.) at some company. Biases outbound company refs on that page
// toward works_at when per-edge verbs are absent (e.g. possessive phrasings
// "her work on Delta's pipeline..." where the verb "works" doesn't appear
// near the slug).
//
// Scope: only fires for person-page → company-page links. Companies' own
// pages mentioning their employees use the page-role layer differently.
/** The first match of each page-role prior in `text`: joined with newlines, they decide every prior exactly as the whole text does (no prior crosses a line). */
export function rolePriorPhrases(text: string): Array<string | null> {
  return [PARTNER_ROLE_RE, ADVISOR_ROLE_RE, EMPLOYEE_ROLE_RE].map(re => re.exec(text)?.[0] ?? null);
}

const EMPLOYEE_ROLE_RE = /\b(?:is an? (?:senior|staff|principal|lead|backend|frontend|full-?stack|ML|data|security|DevOps|platform)? ?engineer at|is an? (?:senior|staff|principal|lead)? ?(?:developer|designer|product manager|engineering manager|director|VP) (?:at|of)|holds? the (?:CTO|CEO|CFO|COO|CMO|CRO|VP) (?:role|position|seat|title) at|is the (?:CTO|CEO|CFO|COO|CMO|CRO) of|employee at|on the team at|works on .{0,30} at)\b/i;


/** A per-edge verb rule. `id` is stable: tests, explainLinkType and development reports name rules by it. */
interface VerbRule { id: string; re: RegExp; verb: string; unit?: TypingUnit }
const CORE_VERB_RULES: ReadonlyArray<VerbRule> = [
  { id: 'verb.founded', re: FOUNDED_RE, verb: 'founded' },
  { id: 'verb.invested_in', re: INVESTED_RE, verb: 'invested_in' },
  { id: 'verb.invested_in.board_seat', re: BOARD_SEAT_RE, verb: 'invested_in' },
  { id: 'verb.advises', re: ADVISES_RE, verb: 'advises' },
  { id: 'verb.works_at', re: WORKS_AT_RE, verb: 'works_at' },
  { id: 'verb.zh.founded', re: ZH_FOUNDED_RE, verb: 'founded' },
  { id: 'verb.zh.invested_in', re: ZH_INVESTED_RE, verb: 'invested_in' },
  { id: 'verb.zh.advises', re: ZH_ADVISES_RE, verb: 'advises' },
  { id: 'verb.zh.works_at', re: ZH_WORKS_AT_RE, verb: 'works_at' },
  { id: 'verb.zh.cited', re: ZH_CITED_RE, verb: 'cited' },
];
/** Core rules with each typing unit's rules right after the core rule they extend (skipped unless the unit is on). */
const VERB_RULES: ReadonlyArray<VerbRule> = CORE_VERB_RULES.flatMap(r => [r, ...UNIT_VERB_RULES.filter(u => u.after === r.id)]);
const ruleOn = (r: VerbRule) => !r.unit || typingUnitEnabled(r.unit);

/**
 * The per-edge verb for one link when its context window holds several links.
 * A verb match belongs to another link when another link sits between it and
 * this one, or when it is written immediately before another link ("... and
 * also advises [Widget]"). Among the matches that are not another link's,
 * precedence decides as before. Returns undefined when the link cannot be
 * located in the window (callers fall back to plain precedence).
 */
const LINK_MARK_RE = /\]\(|\]\]|\[\[/;
// "works at [A] and at [B]": links joined only by commas and conjunctions share the verb before the first.
const INLINE_LINK_RE = /\[\[[^\]\n]*\]\]|\[[^\]\n]*\]\([^)\n]*\)/g;
const CONNECTOR_RE = /^\s*(?:,\s*(?:(?:and|or)\s+)?|(?:and|or|&|as well as)\s+)(?:(?:at|in|with|for|of|to)\s+)?$/i;
const coordinated = (between: string) => {
  const [lead, ...gaps] = between.split(INLINE_LINK_RE);
  return !lead.trim() && gaps.length > 0 && gaps.every(gap => CONNECTOR_RE.test(gap));
};
const GLOBAL_VERB_RULES = VERB_RULES.map(r => ({ ...r, re: new RegExp(r.re.source, `${r.re.flags.replace('g', '')}g`) })); // nosemgrep: javascript.lang.security.audit.detect-non-literal-regexp.detect-non-literal-regexp -- recompiles the module's own literal VERB_RULES patterns
interface Attachment { rule: VerbRule | null; suppressed: string[]; otherLink: boolean }
function attachedVerb(context: string, targetSlug?: string, anchor?: number, explain = false, investorPrior: () => boolean = () => false, targetType?: string | null): Attachment | undefined {
  const fromAnchor = targetSlug && anchor !== undefined ? context.indexOf(targetSlug, anchor) : -1;
  const at = fromAnchor >= 0 ? fromAnchor : targetSlug ? context.indexOf(targetSlug) : -1;
  if (at < 0) return undefined;
  const open = context.lastIndexOf('[', at);
  const linkStart = open >= 0 && at - open <= 120 ? (context[open - 1] === '[' ? open - 1 : open) : at;
  const close = context.slice(at).search(/\)|\]\]/);
  const linkEnd = close >= 0 ? at + close + (context[at + close] === ')' ? 1 : 2) : at + targetSlug!.length;
  const suppressed: string[] = [];
  let rule: VerbRule | null = null;
  let otherLink = false;
  for (const r of GLOBAL_VERB_RULES) {
    if (!ruleOn(r)) continue;
    for (const m of context.matchAll(r.re)) {
      const start = m.index ?? 0; const end = start + m[0].length;
      if ((end <= linkStart && LINK_MARK_RE.test(context.slice(end, linkStart)) && !coordinated(context.slice(end, linkStart)))
        || (start >= linkEnd && (LINK_MARK_RE.test(context.slice(linkEnd, start)) || /^\s*(?:(?:with|at|to|for|of|in|on)\s+)?\[/i.test(context.slice(end))))) {
        otherLink = true;
        if (explain) suppressed.push(`${r.id}:other-link`);
        continue;
      }
      const veto = unitVerbVeto({ rule: r, context, start, end, investorPrior, linkStart, linkEnd });
      if (veto) { suppressed.push(veto); continue; }
      // #6191: a target that cannot take the verb (works_at toward a meeting or person) skips the rule.
      if (!targetTakesVerb(r.verb, targetSlug, targetType)) { if (explain) suppressed.push(`${r.id}:target-role`); continue; }
      if (rule) { suppressed.push(`${r.id}:outranked`); break; }
      rule = r;
      if (!explain) return { rule, suppressed, otherLink };
      break;
    }
  }
  return { rule, suppressed: [...new Set(suppressed)], otherLink };
}

/** Why inferLinkType chose a type: the rule, how it attached, what it suppressed, and the prior. */
export interface LinkTypeTrace {
  type: string;
  /** Stable id of the deciding rule (`verb.*`, `prior.*`, `page.*`, `unit.*`), or null for plain `mentions`. */
  rule: string | null;
  /** attached: the verb belongs to this link; window: the link was not located, plain precedence over the window;
   *  other-links: every verb in the window belongs to another link; none: no verb in the window. */
  attachment: 'attached' | 'window' | 'other-links' | 'none';
  /** Rule ids that matched but did not decide (`:other-link` belonged to another link, `:outranked` lost on precedence). */
  suppressed: string[];
  /** The page-role prior that decided (`prior.investor`, `prior.advisor`, `prior.employee`), if any. */
  prior: string | null;
  /** The typing unit that changed this decision (src/core/link-typing-units.ts), if any. */
  unit: TypingUnit | null;
}

/**
 * Infer link_type from page context. Deterministic regex heuristics, no LLM.
 *
 * Two layers of inference:
 *   1. Per-edge: ~240 char window around the slug mention. Looks for explicit
 *      verbs (FOUNDED_RE, INVESTED_RE, ADVISES_RE, WORKS_AT_RE).
 *   2. Page-role prior: when per-edge inference falls through to 'mentions',
 *      check if the SOURCE page describes the author as a partner/investor.
 *      If yes, bias outbound company refs toward 'invested_in'.
 *
 * Precedence: founded > invested_in > advises > works_at > role prior > mentions.
 *
 * The role-prior layer is what closes the gap on partner bios where the prose
 * lists portfolio companies without repeating the investment verb each time
 * ("Her current board seats reflect her portfolio: [Co A], [Co B], [Co C]").
 */
export function inferLinkType(pageType: PageType, context: string, globalContext?: string, targetSlug?: string, targetType?: string | null, anchor?: number): string {
  return traceLinkType(pageType, context, globalContext, targetSlug, targetType, anchor).type;
}

/** inferLinkType with its reasons. `pageText` is the whole page (role priors read `globalContext`, which timeline links do not get). */
export function traceLinkType(pageType: PageType, context: string, globalContext?: string, targetSlug?: string, targetType?: string | null, anchor?: number, pageText?: string, explain = false): LinkTypeTrace {
  const out = (type: string, rule: string | null, attachment: LinkTypeTrace['attachment'] = 'none', suppressed: string[] = [], prior: string | null = null): LinkTypeTrace =>
    ({ type, rule, attachment, suppressed, prior, unit: unitOfRule(rule) ?? unitOfRule(suppressed.find(id => id.startsWith('unit.'))) });
  if (pageType === 'media') {
    return out('mentions', 'page.media');
  }
  // v0.27.1: image pages link to their text sibling via 'image_of' (the
  // image is OF that meeting/note). Set explicitly by the import-image
  // path-proximity helper, not by markdown extraction — but the type is
  // declared here so graph-query knows the edge name.
  if ((pageType as string) === 'image') return out('image_of', 'page.image');
  if ((pageType as string) === 'meeting') {
    return out(targetType !== undefined ? (targetType === 'person' ? 'attended' : 'mentions')
      : (!targetSlug || targetSlug.startsWith('people/') ? 'attended' : 'mentions'), 'page.meeting');
  }
  // Per-edge verb rules, precedence founded > invested_in > advises > works_at
  // (then the Chinese rules), over the verbs that belong to this link: in
  // "works at [A] and also advises [B]", A is works_at and B advises.
  const investorPrior = () => pageType === 'person' && PARTNER_ROLE_RE.test(pageText ?? globalContext ?? '');
  const attached = attachedVerb(context, targetSlug, anchor, explain, investorPrior, targetType);
  if (attached?.rule) return out(attached.rule.verb, attached.rule.id, 'attached', attached.suppressed);
  const suppressed = attached?.suppressed ?? [];
  if (attached === undefined) {
    for (const r of GLOBAL_VERB_RULES) {
      if (!ruleOn(r)) continue;
      for (const m of context.matchAll(r.re)) {
        const veto = unitVerbVeto({ rule: r, context, start: m.index ?? 0, end: (m.index ?? 0) + m[0].length, investorPrior });
        if (veto) { suppressed.push(veto); continue; }
        if (!targetTakesVerb(r.verb, targetSlug, targetType)) { suppressed.push(`${r.id}:target-role`); continue; }
        return out(r.verb, r.id, 'window', suppressed);
      }
    }
  }
  const attachment = attached?.otherLink ? 'other-links' : 'none';
  // Page-role prior: only fires for person -> company links. Concept pages
  // about VC topics naturally contain "venture capital" in their text, but
  // their company refs are mentions, not investments. Partner pages mentioning
  // other people (co-investors, friends) should also stay as mentions.
  //
  // Precedence within priors: investor > advisor > employee. Investors often
  // also sit on boards ("board seat at portfolio company") which a naive
  // employee/advisor match would mis-classify; keep investor first so those
  // phrasings resolve correctly.
  if (pageType === 'person' && globalContext && targetSlug?.startsWith('companies/')) {
    if (PARTNER_ROLE_RE.test(globalContext)) return out('invested_in', 'prior.investor', attachment, suppressed, 'prior.investor');
    if (ADVISOR_ROLE_RE.test(globalContext)) return out('advises', 'prior.advisor', attachment, suppressed, 'prior.advisor');
    if (EMPLOYEE_ROLE_RE.test(globalContext)) return out('works_at', 'prior.employee', attachment, suppressed, 'prior.employee');
  }
  return out('mentions', null, attachment, suppressed);
}

/** explainLinkType's answer for one target: every occurrence's typing decision, the kept types, tense and dated transitions. */
export interface LinkExplanation {
  target: string;
  occurrences: LinkTypeExplanation[];
  /** The distinct types extractPageLinks emits for the target, sorted (a `mentions` row can sit beside a typed one). */
  types: string[];
  /** Tense per kept temporal type ('past' or 'present'). */
  tense: Record<string, AssertionTense>;
  /** Dated transitions for the kept types, each with the id of the cue that produced it. */
  transitions: Array<DerivedTransition & { rule: string }>;
  /** Validity stints per temporal type, from this page's tense and transitions alone (link-validity.ts buildRelationshipState). */
  stints: Record<string, Stint[]>;
}

/**
 * Why a page links to `target` with the type it does: a pure (database-free, deterministic) replay of
 * extractPageLinks' typing and deriveTemporalEvidence for one page. Shared by tests and development reports.
 * `content` is the page body (compiled truth and timeline); frontmatter links are skipped unless `frontmatter` is given.
 */
export async function explainLinkType(input: {
  slug: string; content: string; pageType: PageType; target: string;
  frontmatter?: Record<string, unknown>; lineGrammar?: ExtractPageLinksOptions['lineGrammar']; pack?: LinkExtractionPack | null;
}): Promise<LinkExplanation> {
  const occurrences: LinkTypeExplanation[] = [];
  const resolver: SlugResolver = { resolve: async () => null };
  const { candidates } = await extractPageLinks(input.slug, input.content, input.frontmatter ?? {}, input.pageType, resolver, {
    skipFrontmatter: !input.frontmatter, lineGrammar: input.lineGrammar, pack: input.pack ?? null,
    explain: e => { if (e.target === input.target) occurrences.push(e); },
  });
  const types = [...new Set(candidates.filter(c => c.targetSlug === input.target).map(c => c.linkType))].sort();
  const transitions: LinkExplanation['transitions'] = [];
  const evidence = deriveTemporalEvidence({ slug: input.slug, compiled_truth: input.content, timeline: '', frontmatter: input.frontmatter ?? {} },
    candidates.map(c => ({ from_slug: c.fromSlug ?? input.slug, to_slug: c.targetSlug, link_type: c.linkType, link_source: c.linkSource ?? 'markdown', origin_field: c.originField ?? null })),
    (t, rule) => { if (t.to_slug === input.target || t.from_slug === input.target) transitions.push({ ...t, rule }); });
  const tense: Record<string, AssertionTense> = {};
  const stints: Record<string, Stint[]> = {};
  for (const t of types) {
    const v = evidence.tense.get(rowKey({ from_slug: input.slug, to_slug: input.target, link_type: t }));
    if (v) tense[t] = v;
    const semantics = relationSemantics(t);
    if (semantics === 'reference') continue;
    stints[t] = buildRelationshipState(semantics, v ? [{ tense: v, originPageId: 1 }] : [],
      transitions.filter(x => x.link_type === t).map(x => ({ kind: x.kind, occurredOn: x.occurred_on, producer: x.producer, originPageId: 1 }))).stints;
  }
  return { target: input.target, occurrences, types, tense, transitions, stints };
}

// ─── Frontmatter link extraction (v0.13) ────────────────────────
//
// YAML frontmatter on entity pages carries rich relationship data:
//
//   company: "Stripe"                       # person page
//   companies: [Stripe, Plaid]              # person page (alias of company)
//   key_people: [Patrick Collison, John]    # company page (incoming works_at)
//   investors: [{name: Sequoia}, Benchmark] # deal page (incoming invested_in)
//   attendees: [Pedro, Garry]               # meeting page (incoming attended)
//
// Each maps to a typed graph edge. The mapping lives here (one source of
// truth) so the three entry points — operations.ts auto-link, extract.ts
// fs source, extract.ts db source — emit identical edges for the same
// frontmatter. This is the point of the v0.13 rewrite.
//
// DIRECTION: "incoming" means the page being written is the TO side;
// the FROM side is the resolved frontmatter value. E.g. `key_people:
// [Pedro]` on company/stripe emits `people/pedro -> companies/stripe
// type=works_at`, preserving subject-of-verb semantics for graph reads.
//
// MULTI-DIR HINTS: investors can be companies, funds, or people. The
// resolver tries each hint in order and takes the first match.

export interface FrontmatterFieldMapping {
  /** Field name(s). Multiple entries are aliases (e.g. company + companies). */
  fields: string[];
  /**
   * Only applies when page.type matches. Omitted = any page type. String
   * (not PageType) because some page types like 'meeting' exist in the
   * pages table without being in the TypeScript PageType enum.
   */
  pageType?: string;
  /** Edge link_type. */
  type: string;
  /** 'outgoing' = page→target. 'incoming' = target→page (subject of verb = from). */
  direction: 'outgoing' | 'incoming';
  /**
   * Target directory hints for slug resolution. Single string or ordered
   * array; resolver tries each. E.g. investors → ['companies', 'funds', 'people'].
   */
  dirHint: string | string[];
}

/**
 * Canonical field → (type, direction, dir-hint) map. Consulted by
 * extractFrontmatterLinks for every YAML field on every written page.
 *
 * NOT normalization: kept as a flat array so duplicate field names with
 * different pageType filters coexist cleanly (vs an object-literal which
 * would last-write-wins on key collision).
 */
export const FRONTMATTER_LINK_MAP: FrontmatterFieldMapping[] = [
  // Person pages → companies
  { fields: ['company', 'companies'], pageType: 'person', type: 'works_at', direction: 'outgoing', dirHint: 'companies' },
  { fields: ['founded'], pageType: 'person', type: 'founded', direction: 'outgoing', dirHint: 'companies' },
  // Company pages (incoming relationships — subject of the verb lives elsewhere)
  { fields: ['key_people'], pageType: 'company', type: 'works_at', direction: 'incoming', dirHint: 'people' },
  { fields: ['partner'], pageType: 'company', type: 'yc_partner', direction: 'incoming', dirHint: 'people' },
  { fields: ['investors'], pageType: 'company', type: 'invested_in', direction: 'incoming',
    dirHint: ['companies', 'funds', 'people'] },
  // Deal pages (all incoming — deals are the object)
  { fields: ['investors'], pageType: 'deal', type: 'invested_in', direction: 'incoming',
    dirHint: ['companies', 'funds', 'people'] },
  { fields: ['lead'], pageType: 'deal', type: 'led_round', direction: 'incoming',
    dirHint: ['companies', 'funds', 'people'] },
  // Meeting pages
  { fields: ['attendees'], pageType: 'meeting', type: 'attended', direction: 'incoming', dirHint: 'people' },
  // Any page type
  { fields: ['sources'], type: 'discussed_in', direction: 'incoming', dirHint: ['source', 'media'] },
  { fields: ['source'], type: 'source', direction: 'outgoing', dirHint: '' /* already slug-shaped */ },
  { fields: ['related', 'see_also'], type: 'related_to', direction: 'outgoing', dirHint: '' },
];

// ─── Slug resolver ──────────────────────────────────────────────

export interface ResolveOptions {
  globalBasename?: boolean;
  selfSlug?: string;
}

export interface SlugResolver {
  resolveAttendance?(name: string, dirHint?: string | string[]): Promise<string | null>;
  /**
   * Resolve a display name to a canonical slug.
   * Returns null when no match meets confidence threshold — callers should
   * skip (not write a dead link) and the unresolved name goes into the
   * extract/put_page summary so the user can see the gap.
   *
   * `globalBasename` (#5749): the caller runs with
   * `link_resolution.global_basename` on, so a unique page whose slug
   * basename is `name` (other than `selfSlug`) resolves before any fuzzy or
   * keyword-search candidate.
   */
  resolve(name: string, dirHint?: string | string[], opts?: ResolveOptions): Promise<string | null>;
  /**
   * Issue #972: return every slug whose basename (final `/`-segment, or
   * the whole slug if it has no `/`) matches `name`. Multi-match by
   * design — `[[struktura]]` referencing both `projects/struktura` and
   * `archive/struktura` returns both; the caller emits one graph edge
   * per result. Returns `[]` when no matches.
   *
   * Optional so existing SlugResolver consumers (e.g. synthetic
   * frontmatter-only resolvers) keep working without code changes.
   * Implementations should make this cheap to call repeatedly within
   * a single extract run (build the index once, reuse it).
   */
  resolveBasenameMatches?(name: string): Promise<string[]>;
}

/**
 * Issue #972 (codex [P2] DRY): the ONE basename matcher. makeResolver, the
 * FS resolver, and the doctor `link_resolution_opportunity` check all
 * build/query through these two functions so they cannot drift.
 *
 * Keying: raw tail + lowercase tail + slugified tail (the final `/`-segment,
 * or the whole slug when it has no `/`). #2367: slugified keys follow
 * slugifySegment (NFD → strip accents → NFC → lowercase → SLUG_WORD_CHARS
 * filter) and then fold stroke letters through latin-fold (#4855), so for
 * names with đ/ø/ł/ß… the key is NOT byte-identical to the page slug sync
 * mints; the dir-hint candidate step (makeResolver step 2, the FS resolver)
 * tries both forms. The old ASCII-only strip emptied CJK basenames.
 */
const BASENAME_KEEP_RE = new RegExp(`[^${SLUG_WORD_CHARS}\\s\\-]`, 'gu');
export function normalizeBasename(s: string): string {
  // The accent strip cannot fold stroke letters \u2014 Unicode gives them no
  // decomposition \u2014 so the shared table runs after it, on both the index and
  // the query side. Without it a display name keeps the unfolded letter while
  // the ASCII page slug does not, and the lookup misses in silence:
  // `[[\u0110\u1ee9c Example]]` keyed `\u0111uc-example` and never found `people/duc-example`.
  const folded = foldNonDecomposingLatin(
    s.normalize('NFD').replace(/[\u0300-\u036f]/g, '').normalize('NFC')
      .replace(SLUG_VARIATION_SELECTORS_RE, '').toLowerCase(), // twin of slugifySegment's strip (#4985)
  );
  return folded.replace(BASENAME_KEEP_RE, '').trim().replace(/\s+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
}

/** Stable order: shorter slug first (likely closer to brain root), then lexical. */
function basenameSort(a: string, b: string): number {
  return (a.length - b.length) || a.localeCompare(b);
}

/** Build a `key → slug[]` index over a slug collection, or add the slugs to `idx`. Keys: raw/lower/slugified tail. */
export function buildBasenameIndex(slugs: Iterable<string>, idx = new Map<string, string[]>()): Map<string, string[]> {
  const addKey = (key: string, slug: string) => {
    const existing = idx.get(key);
    if (existing) { if (!existing.includes(slug)) existing.push(slug); }
    else idx.set(key, [slug]);
  };
  for (const slug of slugs) {
    const tail = slug.includes('/') ? slug.slice(slug.lastIndexOf('/') + 1) : slug;
    addKey(tail, slug);
    const lower = tail.toLowerCase();
    if (lower !== tail) addKey(lower, slug);
    const slugified = normalizeBasename(tail);
    if (slugified && slugified !== tail && slugified !== lower) addKey(slugified, slug);
  }
  return idx;
}

/** Look a name up in a basename index (raw → lower → slugified), stable-sorted. */
export function queryBasenameIndex(idx: Map<string, string[]>, name: string): string[] {
  if (!name || typeof name !== 'string') return [];
  const trimmed = name.trim();
  if (!trimmed) return [];
  const hit = idx.get(trimmed) ?? idx.get(trimmed.toLowerCase()) ?? idx.get(normalizeBasename(trimmed));
  return hit ? [...hit].sort(basenameSort) : [];
}

/**
 * Create a resolver scoped to a single extract run or single put_page call.
 *
 * mode: 'batch' (migration / gbrain extract) — pg_trgm only, NO search
 * fallback. On a 46K-page brain this avoids N-thousand OpenAI embedding
 * calls + Anthropic Haiku expansion calls (see operations-query-hidden-haiku
 * learning) and keeps the backfill deterministic + under a wall-clock budget.
 *
 * mode: 'live' (put_page auto-link) — can afford the (rare, bounded) search
 * fallback for names that don't fuzzy-match. Still passes expand=false to
 * dodge Haiku.
 *
 * cache: per-resolver instance. Same name → same slug lookup every call.
 * Callers never need to dedupe names themselves.
 */
export function makeResolver(
  engine: BrainEngine,
  opts: { mode: 'batch' | 'live'; sourceId?: string; basenameIndex?: () => Promise<Map<string, string[]>> } = { mode: 'live' },
): SlugResolver {
  const cache = new Map<string, string | null>();
  const basenameMatches = new Map<string, string[]>();
  const attendanceCache = new Map<string, string | null>();
  const attendanceCacheLimit = 256;

  // Issue #972: lazy-built basename → slug[] index for global-basename
  // resolution. Built on first call to `resolveBasenameMatches`; reused
  // for the rest of the resolver instance's lifetime. Cost is bounded
  // (one `engine.getAllSlugs()` call per extract run / put_page). The
  // index keys BOTH the raw tail and the slugified-tail so a wikilink
  // `[[Fast-Weigh]]` matches a page slugged `companies/fast-weigh` as
  // well as `notes/Fast-Weigh`.
  let basenameIndex: Map<string, string[]> | null = null;
  async function ensureBasenameIndex(): Promise<Map<string, string[]>> {
    if (basenameIndex !== null) return basenameIndex;
    const idx = new Map<string, string[]>();
    if (opts.basenameIndex) {
      basenameIndex = await opts.basenameIndex().catch(() => idx);
      return basenameIndex;
    }
    if (typeof engine.getAllSlugs !== 'function') {
      basenameIndex = idx;
      return idx;
    }
    try {
      // Issue #972 (codex [P1]): scope the basename index to the resolver's
      // source. getAllSlugs({sourceId}) keeps wikilink resolution from
      // spanning unrelated sources — a bare [[name]] must NOT resolve to a
      // same-tail page in a DIFFERENT source and create a cross-source edge.
      // #972 is "global basename across folders," not "cross-source federation."
      const all = await engine.getAllSlugs(opts.sourceId ? { sourceId: opts.sourceId } : undefined);
      // Issue #972 (codex [P2] DRY): one shared index builder for all surfaces.
      basenameIndex = buildBasenameIndex(all);
      return basenameIndex;
    } catch {
      // Index build failed — empty map → resolveBasenameMatches finds
      // nothing, resolver continues as if the flag was off. Never throw.
    }
    basenameIndex = idx;
    return idx;
  }

  return {
    async resolveAttendance(name: string, dirHint?: string | string[]): Promise<string | null> {
      let value = name.trim();
      const colon = value.indexOf(':');
      if (colon !== -1 && isValidSourceId(value.slice(0, colon))) {
        if (value.slice(0, colon) !== (opts.sourceId ?? 'default')) return null;
        value = value.slice(colon + 1);
      }
      const hints = Array.isArray(dirHint) ? dirHint : dirHint ? [dirHint] : [];
      const cacheKey = JSON.stringify([opts.sourceId ?? 'default', value, hints]);
      if (attendanceCache.has(cacheKey)) return attendanceCache.get(cacheKey)!;
      const slugs = value.includes('/') ? [value] : [...new Set(hints.flatMap(hint =>
        [normalizeBasename(value), slugifySegment(value)].map(form => `${hint}/${form}`)))];
      const matches = await engine.executeRaw<{ slug: string }>(`SELECT slug FROM pages
        WHERE source_id=$1 AND deleted_at IS NULL AND type='person'
          AND (slug=ANY($2::text[]) OR lower(title)=lower($3)
            OR EXISTS (SELECT 1 FROM jsonb_array_elements_text(CASE WHEN jsonb_typeof(frontmatter->'aliases')='array'
              THEN frontmatter->'aliases' ELSE '[]'::jsonb END) alias WHERE lower(alias)=lower($3))) LIMIT 2`,
      [opts.sourceId ?? 'default', slugs, value]);
      const resolved = matches.length === 1 ? matches[0].slug : null;
      if (attendanceCache.size >= attendanceCacheLimit) attendanceCache.clear();
      attendanceCache.set(cacheKey, resolved);
      return resolved;
    },
    async resolveBasenameMatches(name: string): Promise<string[]> {
      // Issue #972 (codex [P2] DRY): shared query so resolver + FS + doctor
      // return the same matches in the same stable order. Memoized per
      // resolver: a shared opts.basenameIndex may grow while a page extracts.
      if (!basenameMatches.has(name)) basenameMatches.set(name, queryBasenameIndex(await ensureBasenameIndex(), name));
      return [...basenameMatches.get(name)!];
    },

    async resolve(name: string, dirHint?: string | string[], resolveOpts?: ResolveOptions): Promise<string | null> {
      if (!name || typeof name !== 'string') return null;
      const trimmed = name.trim();
      if (!trimmed) return null;

      const basenameKey = resolveOpts?.globalBasename ? `\u0000basename:${resolveOpts.selfSlug ?? ''}` : '';
      const cacheKey = `${trimmed}\u0000${Array.isArray(dirHint) ? dirHint.join(',') : (dirHint || '')}${basenameKey}`;
      if (cache.has(cacheKey)) return cache.get(cacheKey)!;

      const hints = Array.isArray(dirHint) ? dirHint : (dirHint ? [dirHint] : []);

      // Step 1: a path-shaped value names its page exactly. Try each exact
      // candidate (the value itself when slug-shaped, then the slug sync
      // mints for that path), then a rename alias. Exact lookups only, so a
      // miss falls through to the steps below and never invents an edge.
      for (const candidate of exactSlugCandidates(trimmed)) {
        // Same source scope as the basename index above (#972): a wikilink in
        // source A must not resolve to a same-slug page in source B.
        const page = await engine.getPage(candidate, opts.sourceId ? { sourceId: opts.sourceId } : undefined); // gbrain-allow-unscoped-getpage: read-only wikilink resolution; unscoped-when-no-source is the documented single-source behavior
        if (page) {
          cache.set(cacheKey, candidate);
          return candidate;
        }
        // A renamed page leaves `old -> new` in slug_aliases; links written
        // against the old slug keep resolving to the page that moved.
        if (typeof engine.resolveSlugWithAlias === 'function') {
          const canonical = await engine.resolveSlugWithAlias(candidate, opts.sourceId ?? 'default');
          if (canonical !== candidate && await engine.getPage(canonical, { sourceId: opts.sourceId ?? 'default' })) {
            cache.set(cacheKey, canonical);
            return canonical;
          }
        }
      }

      // Step 2: dir-hint + slugify → exact getPage. Two grammars (#4855):
      // normalizeBasename (#2367) folds stroke letters to ASCII via latin-fold,
      // while slugifySegment — the page-slug grammar sync mints — keeps them
      // (#3417), so a page synced from `Đức Example.md` lives at the unfolded
      // slug. Exact lookups only, so trying both can never false-positive.
      const forms = new Set([normalizeBasename(trimmed), slugifySegment(trimmed)]);
      for (const hint of hints) {
        if (!hint) continue;
        for (const form of forms) {
          const candidate = `${hint}/${form}`;
          const page = await engine.getPage(candidate, opts.sourceId ? { sourceId: opts.sourceId } : undefined); // gbrain-allow-unscoped-getpage: read-only wikilink resolution; unscoped-when-no-source is the documented single-source behavior
          if (page) {
            cache.set(cacheKey, candidate);
            return candidate;
          }
        }
      }

      // Step 2.5 (#5749): with link_resolution.global_basename on, a unique
      // page whose slug basename IS the name wins before fuzzy or keyword
      // evidence about some other page — the exact-name-first precedence of
      // resolveEntitySlug (#5769). Without it the live keyword step let a
      // transcript that repeats the term take over a correct frontmatter edge.
      if (resolveOpts?.globalBasename) {
        const matches = queryBasenameIndex(await ensureBasenameIndex(), trimmed)
          .filter(s => s !== resolveOpts.selfSlug);
        if (matches.length === 1) {
          cache.set(cacheKey, matches[0]);
          return matches[0];
        }
      }

      // Step 3: pg_trgm fuzzy title match — both modes. Tries each hint in
      // order; first hint with a ≥0.55 similarity match wins. If no hints,
      // try the whole pages table. When opts.sourceId is set, the fuzzy
      // search is constrained to that source (and skips soft-deleted pages)
      // so cross-source slug suggestions don't get silently dropped at the
      // FK filter downstream. Mirrors the same scope fix `tryFuzzyMatch` got
      // via #1436.
      // A person, company, fund or organization candidate must carry the
      // same name tokens (sameEntityName): a near-name like "Carol Exampl" never
      // links to a different person's page and stays unresolved instead.
      const searchHints = hints.length > 0 ? hints : [undefined];
      const confident = async (slug: string): Promise<boolean> => {
        const page = await engine.getPage(slug, opts.sourceId ? { sourceId: opts.sourceId } : undefined); // gbrain-allow-unscoped-getpage: read-only confidence check on a candidate the fuzzy lookup just returned
        return !!page && (!isIdentityEntity(slug, page.type) || sameEntityName(trimmed, page.title, slug));
      };
      for (const hint of searchHints) {
        const match = await engine.findByTitleFuzzy(trimmed, hint, 0.55, opts.sourceId);
        if (match && await confident(match.slug)) {
          cache.set(cacheKey, match.slug);
          return match.slug;
        }
      }

      // Step 4: live-mode ONLY — fall back to hybrid search. expand: false
      // is MANDATORY (see operations-query-hidden-haiku learning). Batch
      // mode skips this step entirely to keep migration deterministic.
      if (opts.mode === 'live') {
        try {
          const results = await engine.searchKeyword(trimmed, { limit: 3, ...(opts.sourceId ? { sourceId: opts.sourceId } : {}) });
          if (results.length > 0 && results[0].score >= 0.8) {
            // Filter by dir hint if provided.
            const top = hints.length > 0
              ? results.find(r => hints.some(h => r.slug.startsWith(`${h}/`)))
              : results[0];
            if (top && (!isIdentityEntity(top.slug, top.type) || sameEntityName(trimmed, top.title, top.slug))) {
              cache.set(cacheKey, top.slug);
              return top.slug;
            }
          }
        } catch { /* search errors are non-fatal; fall through to null */ }
      }

      // Null = unresolvable. Caller records for the unresolved report.
      cache.set(cacheKey, null);
      return null;
    },
  };
}

// ─── Frontmatter extractor ──────────────────────────────────────

/**
 * Unwrap an Obsidian `[[wikilink]]` frontmatter value to its bare link
 * target so the resolver (which expects bare titles / dir slugs) can match
 * it. Mainstream Obsidian authors frontmatter links as `related: ["[[Page]]"]`;
 * without this, the resolver treats the brackets as part of the value and a
 * `[[90-people/nicolai]]` is normalized into `90peoplenicolai`, so it never
 * resolves. Strips a trailing `|alias`, `#heading`, or `^block` suffix — the
 * link target only. The regex is anchored to a wholly-wrapped value
 * (`^\s*\[\[…\]\]\s*$`), so bare titles and any value not fully wrapped pass
 * through unchanged and existing behavior is preserved exactly.
 */
export function unwrapWikilink(value: string): string {
  const match = /^\s*\[\[(.+?)\]\]\s*$/.exec(value);
  if (!match) return value;
  // Take the link target: drop |alias, then #heading / ^block suffixes.
  const target = match[1].split('|')[0].split('#')[0].split('^')[0];
  return target.trim();
}

export interface UnresolvedFrontmatterRef {
  /** The frontmatter field name. */
  field: string;
  /** The name that did not resolve. */
  name: string;
  reason?: 'target_type_mismatch';
}

export interface FrontmatterExtractResult {
  candidates: LinkCandidate[];
  unresolved: UnresolvedFrontmatterRef[];
  attendanceComplete: boolean;
}

/**
 * Extract typed graph edges from YAML frontmatter. Async because the
 * resolver may need to query the DB for fuzzy matches.
 *
 * Arrays of strings: each entry resolved independently.
 * Arrays of objects: uses the `name` or `slug` property (codex tension 6.3).
 * Non-string / non-object entries: silently skipped (log-only).
 */
export async function extractFrontmatterLinks(
  slug: string,
  pageType: PageType,
  frontmatter: Record<string, unknown>,
  resolver: SlugResolver,
  globalBasename = false,
  pack?: LinkExtractionPack | null,
  targetType?: (slug: string) => string | undefined,
  onResolvedTarget?: (slug: string) => void,
): Promise<FrontmatterExtractResult> {
  const candidates: LinkCandidate[] = [];
  const unresolved: UnresolvedFrontmatterRef[] = [];
  let attendanceComplete = true;

  const packMappings: FrontmatterFieldMapping[] = [];
  if (pack && pack.frontmatter_links.length > 0) {
    const seenFields = new Set<string>();
    for (const fl of pack.frontmatter_links) {
      for (const field of fl.fields) {
        if (seenFields.has(field)) continue;
        seenFields.add(field);
        const type = frontmatterLinkTypeFromPack(pack, pageType as string, field);
        if (!type) continue; // no pack rule for this page type
        const expectedType = pack.link_types.find(lt => lt.name === type)?.inference?.target_type;
        const prefixes = pack.page_types?.find(pt => pt.name === expectedType)?.path_prefixes.map(p => p.replace(/^\/+|\/+$/g, ''));
        const legacy = FRONTMATTER_LINK_MAP.find(mapping => mapping.fields.includes(field)
          && (!mapping.pageType || mapping.pageType === pageType));
        const declared = FRONTMATTER_LINK_MAP.find(mapping => mapping.type === type
          && (!mapping.pageType || mapping.pageType === pageType));
        packMappings.push({ fields: [field], type, direction: declared?.direction ?? 'outgoing',
          dirHint: prefixes?.length ? prefixes : legacy?.dirHint ?? '' });
      }
    }
  }

  const overriddenFields = new Set(packMappings.flatMap(mapping => mapping.fields));
  const legacyMappings = FRONTMATTER_LINK_MAP.map(mapping => ({
    ...mapping, fields: mapping.fields.filter(field => !overriddenFields.has(field)),
  }));
  for (const mapping of [...legacyMappings, ...packMappings]) {
    if (mapping.pageType && mapping.pageType !== pageType) continue;
    for (const field of mapping.fields) {
      const value = frontmatter[field];
      if (value == null) continue;
      const entries = Array.isArray(value) ? value : [value];

      for (const entry of entries) {
        // Extract the name to resolve. Strings pass through; objects use
        // the `name` / `slug` / `title` field in that preference order.
        let name: string | null = null;
        let contextExtra = '';
        if (typeof entry === 'string') {
          name = entry;
        } else if (entry && typeof entry === 'object') {
          const obj = entry as Record<string, unknown>;
          const n = obj.name ?? obj.slug ?? obj.title;
          if (typeof n === 'string') {
            name = n;
            // Carry interesting object fields (role, title) into the context.
            const extras: string[] = [];
            if (typeof obj.role === 'string') extras.push(obj.role);
            if (typeof obj.title === 'string' && obj.title !== n) extras.push(obj.title);
            if (extras.length > 0) contextExtra = ` (${extras.join(', ')})`;
          }
        }
        if (!name) continue;   // skip numbers, nulls, malformed objects

        // Accept Obsidian `[[wikilink]]` values in frontmatter link fields by
        // unwrapping to the bare target before resolution. Bare titles pass
        // through unchanged; the original `name` is preserved for the
        // unresolved report and edge context.
        const linkTarget = unwrapWikilink(name);
        const canonicalAttendance = mapping.type === 'attended' && mapping.direction === 'incoming';
        let resolved = await (canonicalAttendance && resolver.resolveAttendance
          ? resolver.resolveAttendance(linkTarget, mapping.dirHint)
          : resolver.resolve(linkTarget, mapping.dirHint, globalBasename ? { globalBasename, selfSlug: slug } : undefined));
        if (!resolved && globalBasename && !(canonicalAttendance && resolver.resolveAttendance)
          && typeof resolver.resolveBasenameMatches === 'function') {
          // Issue #972 follow-up: extend global_basename resolution to
          // frontmatter link fields. resolve() can't reach a bare-title
          // wikilink value (e.g. `sources: "[[2025-12-25_mentor-extraction]]"`)
          // — it has no '/', so the slug-direct getPage is skipped, and the
          // field's dirHint may name folders that don't exist in this brain,
          // so the dir-scoped exact + fuzzy steps miss too. When
          // link_resolution.global_basename is on, fall back to the SAME
          // basename index the body bare-wikilink pass uses. Unique-match-only:
          // ambiguous basenames (e.g. archive duplicates, generic hubs like
          // `_index`) stay unresolved rather than create a wrong edge.
          const matches = (await resolver.resolveBasenameMatches(linkTarget))
            .filter((s) => s !== slug);
          if (matches.length === 1) resolved = matches[0];
        }
        if (!resolved) {
          if (mapping.type === 'attended') attendanceComplete = false;
          unresolved.push({ field, name });
          continue;
        }
        onResolvedTarget?.(resolved);
        const packTargetType = packMappings.includes(mapping)
          ? pack?.link_types.find(lt => lt.name === mapping.type)?.inference?.target_type : undefined;
        const expectedType = canonicalAttendance ? 'person' : packTargetType;
        if (expectedType && (targetType || packTargetType) && targetType?.(resolved) !== expectedType) {
          if (targetType?.(resolved) === undefined && mapping.type === 'attended') attendanceComplete = false;
          unresolved.push({ field, name, reason: 'target_type_mismatch' });
          continue;
        }

        // Outgoing: page → resolved. Incoming: resolved → page.
        const fromSlug = mapping.direction === 'outgoing' ? slug : resolved;
        const toSlug   = mapping.direction === 'outgoing' ? resolved : slug;
        // Context enrichment (review Finding 7): readable in backlink panels
        // and search snippets instead of bare `frontmatter.key_people`.
        const context = `frontmatter.${field}: ${name}${contextExtra}`;

        candidates.push({
          fromSlug,
          targetSlug: toSlug,
          linkType: mapping.type,
          context,
          linkSource: 'frontmatter',
          originSlug: slug,       // the page whose frontmatter created this edge
          originField: field,
        });
      }
    }
  }

  return { candidates, unresolved, attendanceComplete };
}

// ─── Timeline parsing ───────────────────────────────────────────

export interface TimelineCandidate {
  /** ISO date YYYY-MM-DD. */
  date: string;
  /** First-line summary. */
  summary: string;
  /** Optional detail (subsequent lines until next entry/heading). */
  detail: string;
  /**
   * #3957: source label. Pipe-separated bullets split `Source — Summary`
   * (via findTimelineSourceDelimiter, the SAME split the FS extractor in
   * timeline-extract.ts applies), inline citations carry their `[Source: X]`
   * label, everything else defaults to 'markdown'. Pre-fix the DB path left
   * this unset, so callers wrote source='' while the FS path wrote the split
   * label + trimmed summary — the (page_id, date, summary, source) dedup
   * index saw two shapes for the same bullet and every FS-then-DB (or
   * DB-then-FS) re-extraction duplicated the row.
   */
  source?: string;
}

/**
 * #3957 (moved from timeline-extract.ts so BOTH parsers share it): index of
 * the first dash (—, –, -) that can serve as the `Source — Summary`
 * delimiter: it must have whitespace on both sides and sit outside every
 * markdown-link span. Hyphens inside link targets
 * (`../people/alice-example.md`) and dashes inside link labels
 * (`[Deals — Q1 Review](...)`) are content, not delimiters — splitting on
 * them shatters one entry into two fragments whose halves re-insert on
 * every sync (the (page_id, date, summary, source) uniqueness sees each
 * fragment shape as a new row). Returns -1 when the line has no delimiter.
 */
export function findTimelineSourceDelimiter(text: string): number {
  let depth = 0;
  for (let i = 0; i < text.length; i++) {
    const c = text[i];
    if (c === '[' || c === '(') depth++;
    else if (c === ']' || c === ')') { if (depth > 0) depth--; }
    else if (
      depth === 0 &&
      (c === '—' || c === '–' || c === '-') &&
      i > 0 && /\s/.test(text[i - 1]) &&
      i + 1 < text.length && /\s/.test(text[i + 1])
    ) {
      return i;
    }
  }
  return -1;
}

// Match: `- **YYYY-MM-DD** | summary` or `- **YYYY-MM-DD** -- summary`
// or `- **YYYY-MM-DD** - summary` or just `**YYYY-MM-DD** | summary`.
// #3957: the separator run is captured so the parser can apply the
// `Source — Summary` split ONLY to pipe-separated bullets (the canonical
// shape the FS extractor matches); a dash-separated bullet's rest is one
// summary and must not be shattered on its first interior dash.
// Chinese date lines (TIMELINE_LINE_RE_CN): `- 2020年1月2日 | summary` (bold
// optional). Requires the 年/月 markers so plain ASCII `- 2020-01-02 - text`
// does NOT match. Both live in timeline-citations.ts, whose inline-citation
// pass skips the lines they read.

// `### YYYY-MM-DD — summary` headings, as the FS extractor (timeline-extract.ts Format 2) accepts.
export const TIMELINE_HEADING_RE = /^\s*###\s+(\d{4}-\d{2}-\d{2})\s*[\-–—]+\s*(.+?)\s*$/;

/**
 * Parse timeline entries from content. Looks at:
 *   - The full content (most pages have a top-level "## Timeline" heading).
 *   - Free-form `- **DATE** | text` lines anywhere.
 *
 * Skips dates that don't represent valid calendar dates (e.g. 2026-13-45).
 * Multi-line entries: a date line followed by indented or blank-then-text
 * lines until the next date line or section heading.
 */
export function parseTimelineEntries(content: string): TimelineCandidate[] {
  const result: TimelineCandidate[] = [];
  const lines = content.split('\n');

  let i = 0;
  while (i < lines.length) {
    const headingMatch = TIMELINE_HEADING_RE.exec(lines[i]);
    const isHeadingEntry = headingMatch !== null;
    let date: string;
    let summary: string;
    let separator = '';

    if (headingMatch) {
      date = headingMatch[1];
      summary = headingMatch[2].trim();
    } else {
      // Try English bullet format first, then Chinese.
      const lineMatch = TIMELINE_LINE_RE.exec(lines[i]);
      if (lineMatch) {
        date = lineMatch[1];
        separator = lineMatch[2];
        summary = lineMatch[3].trim();
      } else {
        const chineseMatch = TIMELINE_LINE_RE_CN.exec(lines[i]);
        if (!chineseMatch) { i++; continue; }
        // Normalize Chinese date to YYYY-MM-DD.
        date = `${chineseMatch[1]}-${chineseMatch[2].padStart(2, '0')}-${chineseMatch[3].padStart(2, '0')}`;
        separator = chineseMatch[4];
        summary = chineseMatch[5].trim();
      }
    }

    if (!isValidDate(date) || summary.length === 0) { i++; continue; }
    // #4277: backlink materialization historically wrote dated navigation
    // receipts such as `- **2026-06-13** | Referenced in [Acme](../companies/acme.md)`.
    // The date belongs to the backlink write, not to an event involving this
    // entity — treating it as timeline evidence both invents event dates and
    // lets graph-maintenance noise satisfy timeline coverage. Guard on the
    // PRE-split rest (must START with the marker) so a write-through rendered
    // `source — summary` bullet whose summary merely mentions the phrase is
    // untouched. Mirrored in extractTimelineFromContent (timeline-extract.ts)
    // so FS- and DB-side extraction stay in lockstep.
    if (/^Referenced in\s+\[/i.test(summary)) { i++; continue; }
    // #3957: pipe-separated bullets carry the canonical `Source — Summary`
    // shape; split them exactly like the FS extractor (extractTimelineFromContent
    // Format 1) so FS- and DB-extracted rows share one (source, summary) shape
    // and the DB dedup index collapses re-extractions instead of duplicating.
    // Dash-separated bullets and dated headings are one summary — no split.
    let source = 'markdown';
    if (separator.includes('|')) {
      const at = findTimelineSourceDelimiter(summary);
      if (at >= 0) {
        source = summary.slice(0, at).trim();
        summary = summary.slice(at + 1).trim();
      }
    }
    // Collect optional detail lines (indented, until next date or heading).
    const detailLines: string[] = [];
    let j = i + 1;
    while (j < lines.length) {
      const next = lines[j];
      if (TIMELINE_LINE_RE.test(next) || TIMELINE_HEADING_RE.test(next)) break;
      if (/^#{1,6}\s/.test(next) || isMaterializedMarkerLine(next)) break; // #5567: a marker opens the next bullet
      if (next.trim().length === 0 && detailLines.length === 0) {
        // skip leading blank line; if we hit a blank after detail content
        // and still no new entry, treat detail as ended.
        j++;
        continue;
      }
      if (next.trim().length === 0 && detailLines.length > 0) break;
      if (isHeadingEntry || /^\s+/.test(next) || (!next.startsWith('-') && !next.startsWith('*') && !next.startsWith('#'))) {
        detailLines.push(next.trim());
        j++;
        continue;
      }
      break;
    }
    result.push({ date, summary, detail: detailLines.join(' ').trim(), source });
    i = j;
  }

  // Format 3: inline citation — [Source: <source>, YYYY-MM-DD]. The citation
  // convention gbrain's own quality rules require on every brain write;
  // until now this parser (the db-source extract + ingest path) could not
  // see it, so a page whose dates all live in citations scored zero
  // timeline coverage. Kept in sync with extractTimelineFromContent's
  // Format 3 (the fs-source path). Blocks already captured by the timeline
  // bullet pass are skipped (a bullet often carries its own citation).
  for (const entry of parseInlineCitationTimelineEntries(content, {
    skipLine: isDatedTimelineLine,
  })) {
    // #3957: carry the citation's source label in `source` (the dedup-key
    // column) so the row shape matches the FS extractor's Format 3; the
    // human-readable detail is kept for existing consumers.
    result.push({ date: entry.date, summary: entry.summary, detail: `Source: ${entry.source}`, source: entry.source });
  }
  return result;
}

/** Validate date string represents a real calendar date in ISO YYYY-MM-DD form. */
function isValidDate(s: string): boolean {
  if (!/^\d{4}-\d{2}-\d{2}$/.test(s)) return false;
  const [y, mo, d] = s.split('-').map(Number);
  if (mo < 1 || mo > 12) return false;
  if (d < 1 || d > 31) return false;
  // Use Date object as final check (catches 2026-02-30 etc.)
  const dt = new Date(new Date(0).setUTCFullYear(y, mo - 1, d)); // not Date.UTC: it maps years 0-99 to 1900-1999
  return dt.getUTCFullYear() === y && dt.getUTCMonth() === mo - 1 && dt.getUTCDate() === d;
}

/** Input for {@link deriveTimelineAnchor}: a page's identity + its computed content date. */
export interface TimelineAnchorInput {
  slug: string;
  title?: string | null;
  effectiveDate?: Date | string | null;
  effectiveDateSource?: EffectiveDateSource | null;
}

/**
 * Anchor a single timeline entry from a page's computed content date, for pages
 * whose body carries no parseable timeline line.
 *
 * Comms- and calendar-dominated brains keep the date in frontmatter or the
 * filename (slug `2026-04-24-...`), not in the prose, so `parseTimelineEntries`
 * returns nothing and the page-level `timeline` table stays empty even though
 * the page is firmly dated — leaving `get_timeline` and the brain-score
 * `timeline_coverage` component blind to it. This recovers that signal from the
 * already-computed `effective_date` (no re-parsing). (It does NOT feed the
 * facts-based `find_trajectory`, which reads the `facts` table by entity_slug.)
 *
 * Fires ONLY for a trustworthy content date — frontmatter (`event_date` / `date`
 * / `published`) or the `filename` date — never the `fallback` source, which is
 * `updated_at` (link-churn noise, not when the thing happened). Returns null
 * when no trustworthy date is available. Callers MUST apply this only when body
 * parsing yields zero entries, so it can never shadow a real in-body timeline.
 */
export function deriveTimelineAnchor(input: TimelineAnchorInput): TimelineCandidate | null {
  const { slug, title, effectiveDate, effectiveDateSource } = input;
  if (!effectiveDate) return null;
  // 'fallback' === updated_at; the rest ('event_date'|'date'|'published'|'filename')
  // are real content dates. null/undefined source is not trustworthy either.
  if (effectiveDateSource == null || effectiveDateSource === 'fallback') return null;
  const dt = typeof effectiveDate === 'string' ? new Date(effectiveDate) : effectiveDate;
  if (!(dt instanceof Date) || Number.isNaN(dt.getTime())) return null;
  const iso = dt.toISOString().slice(0, 10);
  if (!isValidDate(iso)) return null;
  const summary = (title ?? '').trim() || slug.split('/').pop() || slug;
  return { date: iso, summary, detail: '' };
}

// ─── Auto-link config ───────────────────────────────────────────

/**
 * Read the auto_link config flag. Defaults to TRUE (auto-link is on by default).
 *
 * Accepts as falsy: 'false', '0', 'no', 'off' (case-insensitive, whitespace-trimmed).
 * Anything else (including null, '', 'true', '1', 'yes', garbage) -> true.
 *
 * The config is stored as a string via engine.setConfig/getConfig.
 */
export async function isAutoLinkEnabled(engine: BrainEngine): Promise<boolean> {
  const val = await engine.getConfig('auto_link');
  if (val == null) return true;
  const normalized = val.trim().toLowerCase();
  return !['false', '0', 'no', 'off'].includes(normalized);
}

/**
 * Read the auto_timeline config flag. Defaults to TRUE (on by default).
 * Same truthiness rules as isAutoLinkEnabled. Controls whether put_page
 * parses timeline entries from freshly-written content and inserts them
 * via addTimelineEntriesBatch.
 */
export async function isAutoTimelineEnabled(engine: BrainEngine): Promise<boolean> {
  const val = await engine.getConfig('auto_timeline');
  if (val == null) return true;
  const normalized = val.trim().toLowerCase();
  return !['false', '0', 'no', 'off'].includes(normalized);
}

/**
 * Read the `link_resolution.global_basename` config flag. Defaults to
 * FALSE (opt-in only; existing brains keep ancestor-walk resolution).
 *
 * When TRUE: bare wikilinks like `[[struktura]]` (no DIR_PATTERN prefix)
 * that don't resolve via the existing path are matched against every
 * page's basename. Each unique match emits a graph edge tagged
 * `linkType: 'wikilink_basename'`. Multiple matches emit multiple edges.
 *
 * Resolution order (highest → lowest):
 *   1. Env var `GBRAIN_LINK_RESOLUTION_GLOBAL_BASENAME=1` (operator override)
 *   2. DB plane via `engine.getConfig('link_resolution.global_basename')`
 *   3. Default false
 *
 * Closes https://github.com/garrytan/gbrain/issues/972.
 */
export async function isGlobalBasenameEnabled(engine: BrainEngine): Promise<boolean> {
  const envVal = process.env.GBRAIN_LINK_RESOLUTION_GLOBAL_BASENAME;
  if (envVal != null) {
    const normalized = envVal.trim().toLowerCase();
    return ['1', 'true', 'yes', 'on'].includes(normalized);
  }
  const val = await engine.getConfig('link_resolution.global_basename');
  if (val == null) return false;
  const normalized = val.trim().toLowerCase();
  return ['1', 'true', 'yes', 'on'].includes(normalized);
}

/**
 * Read the `link_resolution.cross_source` config flag. Defaults to FALSE
 * (opt-in only; the historical same-source-or-'default' edge gate is
 * preserved for existing brains).
 *
 * When TRUE: a wikilink whose target slug exists ONLY in other sources
 * (neither the origin page's source nor 'default') still produces an edge,
 * with `to_source_id` picked deterministically (lexicographically smallest
 * matching source). When FALSE, those candidates are dropped — but counted
 * and surfaced in the extract summary, never silent (issue #2589: the drop
 * was previously indistinguishable from an unresolved link).
 *
 * SCOPE: the DB extract paths (`extract links --source db`, `extract --stale`),
 * the mention scan (`findMentionedEntities` callers lift their guard under it),
 * and the serve-resident maintenance sweep (`sweep.ts`, #3757 — it threads the
 * same flag so its reconcile keeps the edges the CLI lanes created).
 * The FS-walk paths (dir-driven, incl. the autopilot cycle's extract phase)
 * build their slug set from the walked files of ONE source, so cross-source
 * targets aren't resolvable there; FS-walk parity is a filed follow-up.
 *
 * Resolution order (highest → lowest):
 *   1. Env var `GBRAIN_LINK_RESOLUTION_CROSS_SOURCE=1` (operator override)
 *   2. DB plane via `engine.getConfig('link_resolution.cross_source')`
 *   3. Default false
 *
 * Closes https://github.com/garrytan/gbrain/issues/2589.
 */
export async function isCrossSourceLinksEnabled(engine: BrainEngine): Promise<boolean> {
  const envVal = process.env.GBRAIN_LINK_RESOLUTION_CROSS_SOURCE;
  if (envVal != null) {
    const normalized = envVal.trim().toLowerCase();
    return ['1', 'true', 'yes', 'on'].includes(normalized);
  }
  const val = await engine.getConfig('link_resolution.cross_source');
  if (val == null) return false;
  const normalized = val.trim().toLowerCase();
  return ['1', 'true', 'yes', 'on'].includes(normalized);
}