fix: recall exact slug match as search candidate

When searching for a skill by its exact slug (e.g. 'ima-all-ai'), the
result could be missing from the candidate pool because:

1. The vector search candidate pool (75-256) might not include the skill
2. matchesExactTokens uses `.some()` (by design, see #27), so unrelated
   skills with common tokens like 'ai' inflate exactMatches count
3. When exactMatches >= limit, lexicalFallbackSkills is skipped entirely,
   along with its exact slug lookup via the by_slug index

Fix: after all recall stages (vector + exactMatches + lexicalFallback),
reconstruct the candidate slug from query tokens and check if it exists
in merged results. If missing, perform a single O(1) index lookup via
the new `lookupExactSlug` internalQuery to ensure it enters the
candidate pool. It then participates in normal scoring and ranking —
SLUG_EXACT_BOOST (1.4) makes it very likely to rank first, but the
fix does not force any particular ranking.

Co-Authored-By: 戴硕 <daishuo@gmail.com>

Author: oolong-tea-2026

convex/search.test.ts

@@ -17,6 +17,13 @@ vi.mock('./lib/badges', () => ({
     Boolean(skill.badges?.highlighted),
 }))
 
+type SkillSearchEntry = {
+  skill: { slug: string; _id: string }
+  version: unknown
+  ownerHandle: string | null
+  owner: unknown
+}
+
 type WrappedHandler = {
   _handler: (
     ctx: unknown,
@@ -186,7 +193,8 @@ describe('search helpers', () => {
     const runQuery = vi
       .fn()
       .mockResolvedValueOnce(vectorEntries) // hydrateResults
-      .mockResolvedValueOnce(fallbackEntries) // lexicalFallbackSkills
+      .mockResolvedValueOnce(fallbackEntries) // lexicalFallbackSkills (triggered because exactMatches=2 < limit=5)
+      .mockResolvedValueOnce(null) // lookupExactSlug (no exact slug "foo")
 
     const result = await searchSkillsHandler(
       {
@@ -196,12 +204,12 @@ describe('search helpers', () => {
         ]),
         runQuery,
       },
-      { query: 'foo', limit: 2 },
+      { query: 'foo', limit: 5 },
     )
 
-    expect(result).toHaveLength(2)
+    expect(result).toHaveLength(3)
     expect(result[0].skill.slug).toBe('foo-b')
-    expect(new Set(result.map((entry: { skill: { _id: string } }) => entry.skill._id)).size).toBe(2)
+    expect(new Set(result.map((entry: { skill: { _id: string } }) => entry.skill._id)).size).toBe(3)
   })
 
   it('filters suspicious vector results in hydrateResults when requested', async () => {
@@ -515,6 +523,7 @@ describe('search helpers', () => {
           owner: null,
         }))
       }
+      if ('slug' in args) return null // lookupExactSlug
       return [] // lexicalFallbackSkills
     })
 
@@ -533,6 +542,101 @@ describe('search helpers', () => {
     expect(overlap).toHaveLength(0)
   })
 
+  it('recalls exact slug match even when vector search and lexical fallback both miss it', async () => {
+    generateEmbeddingMock.mockResolvedValueOnce([0, 1, 2])
+
+    // Vector search returns candidates that don't include the exact slug "ima-all-ai".
+    // All candidates have "ai" in their summary so matchesExactTokens (which uses `some`)
+    // will pass them, making exactMatches >= limit and skipping lexicalFallback entirely.
+    const vectorEntries = Array.from({ length: 12 }, (_, i) => ({
+      embeddingId: `skillEmbeddings:e${i}`,
+      skill: makePublicSkill({
+        id: `skills:other${i}`,
+        slug: `other-ai-skill-${i}`,
+        displayName: `Other AI Skill ${i}`,
+      }),
+      version: null,
+      ownerHandle: 'owner',
+      owner: { _id: 'users:owner', handle: 'owner', name: 'Owner' },
+    }))
+
+    // The exact slug skill that should be recalled.
+    const exactSlugSkill = {
+      skill: makePublicSkill({
+        id: 'skills:ima',
+        slug: 'ima-all-ai',
+        displayName: 'IMA All AI',
+        downloads: 100,
+      }),
+      version: null,
+      ownerHandle: 'owner',
+      owner: { _id: 'users:owner', handle: 'owner', name: 'Owner' },
+    }
+
+    let lookupSlugCalled = false
+    const runQuery = vi.fn(async (_ref: unknown, args: Record<string, unknown>) => {
+      if ('embeddingIds' in args) return vectorEntries // hydrateResults
+      if ('slug' in args) {
+        lookupSlugCalled = true
+        return args.slug === 'ima-all-ai' ? exactSlugSkill : null // lookupExactSlug
+      }
+      return [] // lexicalFallbackSkills (should not be called)
+    })
+
+    const result = await searchSkillsHandler(
+      {
+        vectorSearch: vi.fn().mockResolvedValue(
+          vectorEntries.map((e) => ({ _id: e.embeddingId, _score: 0.5 })),
+        ),
+        runQuery,
+      },
+      { query: 'ima-all-ai', limit: 10 },
+    )
+
+    expect(lookupSlugCalled).toBe(true)
+    expect(result.some((e: { skill: { slug: string } }) => e.skill.slug === 'ima-all-ai')).toBe(true)
+    // With SLUG_EXACT_BOOST + NAME_EXACT_BOOST, it should be ranked first.
+    expect(result[0].skill.slug).toBe('ima-all-ai')
+  })
+
+  it('skips exact slug lookup when slug is already in merged results', async () => {
+    generateEmbeddingMock.mockResolvedValueOnce([0, 1, 2])
+
+    const imaEntry = {
+      embeddingId: 'skillEmbeddings:ima',
+      skill: makePublicSkill({
+        id: 'skills:ima',
+        slug: 'ima-all-ai',
+        displayName: 'IMA All AI',
+      }),
+      version: null,
+      ownerHandle: 'owner',
+      owner: null,
+    }
+
+    let lookupSlugCalled = false
+    const runQuery = vi.fn(async (_ref: unknown, args: Record<string, unknown>) => {
+      if ('embeddingIds' in args) return [imaEntry]
+      if ('slug' in args) {
+        lookupSlugCalled = true
+        return null
+      }
+      return []
+    })
+
+    await searchSkillsHandler(
+      {
+        vectorSearch: vi.fn().mockResolvedValue([
+          { _id: 'skillEmbeddings:ima', _score: 0.9 },
+        ]),
+        runQuery,
+      },
+      { query: 'ima-all-ai', limit: 10 },
+    )
+
+    expect(lookupSlugCalled).toBe(false)
+  })
+
   it('merges fallback matches without duplicate skill ids', () => {
     const primary = [
       {

convex/search.ts

@@ -200,7 +200,25 @@ export const searchSkills: ReturnType<typeof action> = action({
             nonSuspiciousOnly: args.nonSuspiciousOnly,
           })) as SkillSearchEntry[])
 
-    const mergedMatches = mergeUniqueBySkillId(exactMatches, fallbackMatches)
+    let mergedMatches = mergeUniqueBySkillId(exactMatches, fallbackMatches)
+
+    // Ensure an exact slug match is always recalled, even when the vector
+    // candidate pool and lexical fallback both missed it.  The candidate
+    // slug is reconstructed from query tokens (e.g. "ima all ai" → "ima-all-ai").
+    const candidateSlug = queryTokens.join('-')
+    if (
+      /^[a-z0-9][a-z0-9-]*$/.test(candidateSlug) &&
+      !mergedMatches.some((e) => e.skill.slug === candidateSlug)
+    ) {
+      const exactSlugEntry = (await ctx.runQuery(internal.search.lookupExactSlug, {
+        slug: candidateSlug,
+        highlightedOnly: args.highlightedOnly,
+        nonSuspiciousOnly: args.nonSuspiciousOnly,
+      })) as SkillSearchEntry | null
+      if (exactSlugEntry) {
+        mergedMatches = [exactSlugEntry, ...mergedMatches]
+      }
+    }
 
     return mergedMatches
       .map((entry) => {
@@ -274,6 +292,36 @@ export const hydrateResults = internalQuery({
   },
 })
 
+export const lookupExactSlug = internalQuery({
+  args: {
+    slug: v.string(),
+    highlightedOnly: v.optional(v.boolean()),
+    nonSuspiciousOnly: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args): Promise<SkillSearchEntry | null> => {
+    const slug = args.slug.trim().toLowerCase()
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(slug)) return null
+    const skill = await ctx.db
+      .query('skills')
+      .withIndex('by_slug', (q) => q.eq('slug', slug))
+      .unique()
+    if (!skill || skill.softDeletedAt) return null
+    if (args.nonSuspiciousOnly && isSkillSuspicious(skill)) return null
+    if (args.highlightedOnly && !isSkillHighlighted(skill)) return null
+    const publicSkill = toPublicSkill(skill)
+    if (!publicSkill) return null
+    const getOwnerInfo = makeOwnerInfoGetter(ctx)
+    const resolved = await getOwnerInfo(skill.ownerUserId)
+    if (!resolved.owner) return null
+    return {
+      skill: publicSkill,
+      version: null as Doc<'skillVersions'> | null,
+      ownerHandle: resolved.ownerHandle,
+      owner: resolved.owner,
+    }
+  },
+})
+
 export const lexicalFallbackSkills = internalQuery({
   args: {
     query: v.string(),