Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* 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);
}