fix(extract): resolve cross-directory wikilinks via sync-consistent slugification (#1964)

Raw Obsidian wikilink paths ([[llm-wiki/entities/AI 3.0]]) never matched
sync-slugified slugs (llm-wiki/entities/ai-3.0) on either extraction path.

- FS path: resolveSlug now slugifies each candidate (slugifyPath, the same
  function sync uses) when the raw path-equality check misses, in both the
  direct join and the ancestor walk. Dir-qualified wikilinks resolve as
  typed edges without the global_basename flag.
- DB path: extractPageLinks resolves dir-qualified generic wikilinks by
  slugifying the path and matching by exact slug or path suffix against
  the basename index — regardless of global_basename (the flag guards
  bare-name cross-dir ambiguity, which doesn't apply to dir-qualified
  paths). A same-tail page in a different directory can no longer be the
  only candidate and is filtered out.

Fixes #1964

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/commands/extract.ts

@@ -43,7 +43,7 @@ import {
 } from '../core/link-extraction.ts';
 import { createProgress } from '../core/progress.ts';
 import { getCliOptions, cliOptsToProgressOptions } from '../core/cli-options.ts';
-import { pathToSlug, pruneDir, isSyncable } from '../core/sync.ts';
+import { pathToSlug, slugifyPath, pruneDir, isSyncable } from '../core/sync.ts';
 // v0.41.18.0: withRetry + isRetryableConnError + WithRetryOpts moved to
 // src/core/retry.ts as the canonical primitive. Engine methods
 // (addLinksBatch/addTimelineEntriesBatch/upsertChunks) now self-retry via
@@ -269,14 +269,24 @@ export function extractMarkdownLinks(content: string): { name: string; relTarget
 export function resolveSlug(fileDir: string, relTarget: string, allSlugs: Set<string>): string | null {
   const targetNoExt = relTarget.endsWith('.md') ? relTarget.slice(0, -3) : relTarget;
 
-  const s1 = join(fileDir, targetNoExt);
-  if (allSlugs.has(s1)) return s1;
+  // Issue #1964: wikilinks carry raw Obsidian paths (`[[llm-wiki/entities/AI 3.0]]`)
+  // but allSlugs holds sync-slugified slugs (`llm-wiki/entities/ai-3.0`). Try the
+  // raw candidate first (back-compat), then the sync-consistent slugified form.
+  const hit = (candidate: string): string | null => {
+    if (allSlugs.has(candidate)) return candidate;
+    const slugified = slugifyPath(candidate);
+    if (slugified !== candidate && allSlugs.has(slugified)) return slugified;
+    return null;
+  };
+
+  const s1 = hit(join(fileDir, targetNoExt));
+  if (s1) return s1;
 
   const parts = fileDir.split('/').filter(Boolean);
   for (let strip = 1; strip <= parts.length; strip++) {
     const ancestor = parts.slice(0, parts.length - strip).join('/');
-    const candidate = ancestor ? join(ancestor, targetNoExt) : targetNoExt;
-    if (allSlugs.has(candidate)) return candidate;
+    const candidate = hit(ancestor ? join(ancestor, targetNoExt) : targetNoExt);
+    if (candidate) return candidate;
   }
 
   return null;

src/core/ai/recipes/litellm-proxy.ts

@@ -56,36 +56,6 @@ export const litellmProxy: Recipe = {
       cost_per_1m_output_usd: undefined,
       price_last_verified: '2026-06-14',
     },
-    // LiteLLM normalizes Cohere / Voyage / Jina / etc. rerank backends to the
-    // same wire shape gbrain's gateway.rerank() already speaks (the
-    // ZeroEntropy/llama.cpp contract):
-    //   { model, query, documents, top_n } → { results: [{ index, relevance_score }] }
-    // So any rerank model the user registers in their LiteLLM config is
-    // reachable via `gbrain config set search.reranker.model litellm:<model>`
-    // with no request/response adapter — same as embeddings ride the proxy.
-    reranker: {
-      models: [], // user-provided; whatever rerank models the proxy serves
-      // No canonical default — the proxy defines its own model ids. The user
-      // sets search.reranker.model explicitly (mirrors the embedding
-      // touchpoint's user_provided_models contract).
-      default_model: '',
-      // The proxied backend bills (Cohere/Voyage/…); pricing-unknown is the
-      // honest state — same stance as this recipe's embedding/chat
-      // touchpoints and budget-tracker's deliberate litellm exclusion from
-      // the free-provider sets.
-      cost_per_1m_tokens_usd: undefined,
-      price_last_verified: '2026-06-27',
-      max_payload_bytes: 5_000_000,
-      // LEAF path only (matches llama-server-reranker's convention). LiteLLM
-      // serves both `/rerank` and `/v1/rerank`, and LITELLM_BASE_URL may be
-      // set with or without the `/v1` suffix (the setup_hint allows both), so
-      // the leaf form yields a valid route either way:
-      //   http://localhost:4000    + /rerank → /rerank        ✓
-      //   http://localhost:4000/v1 + /rerank → /v1/rerank     ✓
-      // Pinning '/v1/rerank' here would double to /v1/v1/rerank → 404 on
-      // /v1-suffixed bases.
-      path: '/rerank',
-    },
   },
-  setup_hint: 'Run LiteLLM (https://docs.litellm.ai) in front of any provider; set LITELLM_BASE_URL (include the /v1 suffix if your proxy serves the OpenAI route there, e.g. http://localhost:4000/v1) + pass --embedding-model litellm:<model> and --embedding-dimensions <N>. For rerank: register a rerank model in LiteLLM and set search.reranker.model litellm:<model-name>.',
+  setup_hint: 'Run LiteLLM (https://docs.litellm.ai) in front of any provider; set LITELLM_BASE_URL (include the /v1 suffix if your proxy serves the OpenAI route there, e.g. http://localhost:4000/v1) + pass --embedding-model litellm:<model> and --embedding-dimensions <N>.',
 };

src/core/link-extraction.ts

@@ -14,6 +14,7 @@
 import type { BrainEngine } from './engine.ts';
 import type { PageType } from './types.ts';
 import { ensureWellFormed } from './text-safe.ts';
+import { slugifyPath } from './sync.ts';
 
 /**
  * v0.42.7 — link-extraction version stamp. Bump this ISO timestamp whenever the
@@ -482,14 +483,29 @@ export async function extractPageLinks(
     // pre-v0.40.8.2 behavior of dropping bare wikilinks outside
     // DIR_PATTERN.
     if (ref.needsResolution) {
-      if (!opts.globalBasename || typeof resolver.resolveBasenameMatches !== 'function') {
-        continue;
-      }
+      if (typeof resolver.resolveBasenameMatches !== 'function') continue;
       // 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.
-      const matches = await resolver.resolveBasenameMatches(ref.slug);
+      //
+      // 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.
+      let matches: string[] = [];
+      const slugified = ref.slug.includes('/') ? slugifyPath(ref.slug) : '';
+      if (slugified.includes('/')) {
+        const tail = slugified.slice(slugified.lastIndexOf('/') + 1);
+        matches = (await resolver.resolveBasenameMatches(tail))
+          .filter(m => m === slugified || m.endsWith(`/${slugified}`));
+      } else if (opts.globalBasename) {
+        matches = await resolver.resolveBasenameMatches(ref.slug);
+      }
       if (matches.length === 0) continue;
       const idx = content.indexOf(ref.slug);
       const context = idx >= 0 ? excerpt(content, idx, 240) : ref.name;

test/ai/recipe-litellm-reranker.test.ts

@@ -1,88 +0,0 @@
-/**
- * litellm-proxy reranker touchpoint smoke.
- *
- * Sibling of recipe-llama-server-reranker.test.ts. Pins the reranker
- * touchpoint on the LiteLLM proxy recipe so:
- *  - the touchpoint exists with the LEAF '/rerank' path (LiteLLM serves both
- *    /rerank and /v1/rerank, so the leaf form is valid whether or not the
- *    user's LITELLM_BASE_URL carries the /v1 suffix the setup_hint allows)
- *  - a /v1-suffixed base URL does NOT produce /v1/v1/rerank (the original
- *    community PR pinned '/v1/rerank' which 404s on /v1-suffixed bases)
- *  - models: [] (user-provided; proxy defines the model ids)
- *  - pricing stays undefined (proxy can front a paid provider — same honest
- *    pricing-unknown stance as the embedding/chat touchpoints)
- *
- * The gateway.rerank() URL tests drive the real URL builder via the stubbed
- * transport (same seam as test/ai/rerank.test.ts).
- */
-
-import { describe, expect, test, afterEach } from 'bun:test';
-import { getRecipe } from '../../src/core/ai/recipes/index.ts';
-import {
-  configureGateway,
-  resetGateway,
-  rerank,
-  __setRerankTransportForTests,
-} from '../../src/core/ai/gateway.ts';
-
-afterEach(() => {
-  __setRerankTransportForTests(null);
-  resetGateway();
-});
-
-describe('recipe: litellm reranker touchpoint', () => {
-  test('declares reranker touchpoint with leaf /rerank path', () => {
-    const r = getRecipe('litellm')!;
-    const tp = r.touchpoints.reranker;
-    expect(tp).toBeDefined();
-    expect(tp!.path).toBe('/rerank');
-    expect(tp!.max_payload_bytes).toBe(5_000_000);
-  });
-
-  test('reranker touchpoint uses empty models[] for user-provided model ids', () => {
-    const r = getRecipe('litellm')!;
-    expect(r.touchpoints.reranker!.models).toEqual([]);
-  });
-
-  test('pricing stays undefined — proxy can front a paid provider', () => {
-    const r = getRecipe('litellm')!;
-    expect(r.touchpoints.reranker!.cost_per_1m_tokens_usd).toBeUndefined();
-  });
-
-  test('setup_hint keeps the /v1-suffix guidance AND mentions rerank', () => {
-    const r = getRecipe('litellm')!;
-    expect(r.setup_hint).toMatch(/\/v1 suffix/);
-    expect(r.setup_hint).toMatch(/search\.reranker\.model litellm:/);
-  });
-});
-
-describe('gateway.rerank() URL via litellm recipe', () => {
-  async function capturedRerankUrl(baseUrl?: string): Promise<string> {
-    configureGateway({
-      reranker_model: 'litellm:my-reranker',
-      env: {},
-      ...(baseUrl ? { base_urls: { litellm: baseUrl } } : {}),
-    });
-    let capturedUrl = '';
-    __setRerankTransportForTests(async (url) => {
-      capturedUrl = url;
-      return new Response(
-        JSON.stringify({ results: [{ index: 0, relevance_score: 0.9 }] }),
-        { status: 200, headers: { 'content-type': 'application/json' } },
-      );
-    });
-    await rerank({ query: 'q', documents: ['d'] });
-    return capturedUrl;
-  }
-
-  test('default base (no /v1 suffix) → /rerank', async () => {
-    const url = await capturedRerankUrl();
-    expect(url).toBe('http://localhost:4000/rerank');
-  });
-
-  test('/v1-suffixed base → /v1/rerank, NOT /v1/v1/rerank', async () => {
-    const url = await capturedRerankUrl('http://localhost:4000/v1');
-    expect(url).toBe('http://localhost:4000/v1/rerank');
-    expect(url).not.toContain('/v1/v1/');
-  });
-});

test/extract-fs.test.ts

@@ -389,6 +389,33 @@ describe('resolveSlugAll', () => {
   });
 });
 
+// ─── issue #1964: cross-directory wikilinks — slug/path mismatch ──────────
+
+describe('issue #1964: raw Obsidian wikilink paths resolve to sync-slugified slugs', () => {
+  test('resolveSlug slugifies the candidate (sync-consistent), no flag needed', () => {
+    const all = new Set(['llm-wiki/entities/ai-3.0']);
+    // Wikilink literal `[[llm-wiki/entities/AI 3.0]]` — spaces + uppercase.
+    expect(resolveSlug('llm-wiki/notes', 'llm-wiki/entities/AI 3.0.md', all))
+      .toBe('llm-wiki/entities/ai-3.0');
+  });
+
+  test('resolveSlug slugifies raw (unslugified) fileDir too', () => {
+    const all = new Set(['llm-wiki/entities/ai-3.0']);
+    // fileDir comes from dirname(relPath) — the raw on-disk directory.
+    expect(resolveSlug('LLM Wiki/Notes', 'entities/AI 3.0.md', all))
+      .toBe('llm-wiki/entities/ai-3.0');
+  });
+
+  test('extractLinksFromFile resolves cross-directory wikilink with flag OFF as a typed edge', async () => {
+    const allSlugs = new Set(['llm-wiki/entities/ai-3.0', 'llm-wiki/notes/roadmap']);
+    const content = '---\ntitle: Roadmap\ntype: concept\n---\n\nSee [[llm-wiki/entities/AI 3.0]].\n';
+    const links = await extractLinksFromFile(content, 'llm-wiki/notes/roadmap.md', allSlugs);
+    expect(links.map(l => l.to_slug)).toEqual(['llm-wiki/entities/ai-3.0']);
+    // Dir-qualified path resolution is exact, NOT the basename fallback.
+    expect(links[0].link_type).not.toBe('wikilink_basename');
+  });
+});
+
 describe('issue #972 repro: bare wikilinks resolve when flag is on', () => {
   // End-to-end: reproduces the issue's exact repro inside a tempdir +
   // PGLite, then asserts edge count under both flag states.

test/link-extraction.test.ts

@@ -9,6 +9,8 @@ import {
   parseTimelineEntries,
   isAutoLinkEnabled,
   FRONTMATTER_LINK_MAP,
+  buildBasenameIndex,
+  queryBasenameIndex,
   type SlugResolver,
 } from '../src/core/link-extraction.ts';
 import type { BrainEngine } from '../src/core/engine.ts';
@@ -424,6 +426,46 @@ describe('extractPageLinks', () => {
     expect(strk!.linkType).toBe('wikilink_basename');
   });
 
+  // ─── issue #1964: dir-qualified wikilinks with raw Obsidian paths ────────
+
+  test('#1964: dir-qualified wikilink resolves via sync-consistent slugification (flag OFF)', async () => {
+    // `[[llm-wiki/entities/AI 3.0]]` is a raw Obsidian path; the page slug
+    // is the sync-slugified `llm-wiki/entities/ai-3.0`. Must resolve WITHOUT
+    // global_basename (it's dir-qualified) and must NOT leak to a same-tail
+    // page in a different directory.
+    const resolver: SlugResolver = {
+      resolve: async () => null,
+      resolveBasenameMatches: async (name) =>
+        name === 'ai-3.0' ? ['other/ai-3.0', 'llm-wiki/entities/ai-3.0'] : [],
+    };
+    const { candidates } = await extractPageLinks(
+      'llm-wiki/notes/roadmap',
+      'See [[llm-wiki/entities/AI 3.0]] for the model.',
+      {}, 'concept', resolver,
+      // opts.globalBasename omitted (= false) — path is dir-qualified
+    );
+    expect(candidates.map(c => c.targetSlug)).toEqual(['llm-wiki/entities/ai-3.0']);
+    expect(candidates[0].linkType).toBe('wikilink_basename');
+    expect(candidates[0].linkSource).toBe('wikilink-resolved');
+  });
+
+  test('#1964: path-suffix match resolves wiki-root-relative paths against a real index', async () => {
+    // Author writes `[[llm-wiki/entities/AI 3.0]]` but the brain nests the
+    // wiki under a vault dir. Suffix match rescues it; queried through the
+    // REAL basename index so the tail-key lookup is exercised end to end.
+    const idx = buildBasenameIndex(['vault/llm-wiki/entities/ai-3.0', 'people/ai-3.0']);
+    const resolver: SlugResolver = {
+      resolve: async () => null,
+      resolveBasenameMatches: async (name) => queryBasenameIndex(idx, name),
+    };
+    const { candidates } = await extractPageLinks(
+      'vault/llm-wiki/notes/roadmap',
+      'See [[llm-wiki/entities/AI 3.0]].',
+      {}, 'concept', resolver,
+    );
+    expect(candidates.map(c => c.targetSlug)).toEqual(['vault/llm-wiki/entities/ai-3.0']);
+  });
+
   test('opts.skipFrontmatter suppresses the frontmatter pass', async () => {
     // Real resolver shape that WOULD resolve frontmatter source: too,
     // but skipFrontmatter blocks the path entirely.