feat: skills normalization pipeline, typeahead API, and skill-position links (#64)

* feat(jetstream): index skill-position links from position records

* feat(routes): add skills typeahead search API

Add GET /api/skills/search endpoint with pg_trgm similarity matching
on canonical_name and aliases. Returns skills ordered by similarity
score then user_count. Includes canonical_skills schema, migration,
and integration tests.

* feat: add skill normalization service, updated indexer, and complete migration

Adds skill-normalization.ts with normalizeSkillName, createSlug, and
resolveSkill pipeline. Updates skill indexer to resolve against canonical
registry and manage user_count. Fixes migration to include all tables
(pg_trgm, unresolved_skills, skill_position_links, canonical_skill_id).
Adds canonicalSkillId column to skills schema. Part of #61.

* feat(routes): include skill-position links in profile response

Skills now include positionRkeys showing which roles used them.
Positions now include skillRkeys showing which skills were used.
Part of #61.

* fix(tests): replace non-null assertions with optional chaining in normalization tests

* style: fix prettier formatting

drizzle/0012_canonical_skills.sql

···
+-- Enable pg_trgm for fuzzy matching in typeahead
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+
+CREATE TABLE IF NOT EXISTS "canonical_skills" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+  "canonical_name" text NOT NULL,
+  "slug" text NOT NULL UNIQUE,
+  "category" text,
+  "subcategory" text,
+  "aliases" text[] NOT NULL DEFAULT '{}',
+  "wikidata_id" text,
+  "user_count" integer NOT NULL DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS "canonical_skills_slug_idx" ON "canonical_skills" ("slug");
+CREATE INDEX IF NOT EXISTS "canonical_skills_trgm_idx" ON "canonical_skills" USING gin ("canonical_name" gin_trgm_ops);
+
+CREATE TABLE IF NOT EXISTS "unresolved_skills" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+  "raw_name" text NOT NULL,
+  "normalized_name" text NOT NULL UNIQUE,
+  "occurrences" integer NOT NULL DEFAULT 1,
+  "first_seen_at" timestamp with time zone NOT NULL DEFAULT now(),
+  "resolved_at" timestamp with time zone,
+  "resolved_to_id" uuid REFERENCES "canonical_skills"("id")
+);
+
+CREATE TABLE IF NOT EXISTS "skill_position_links" (
+  "did" text NOT NULL REFERENCES "profiles"("did") ON DELETE CASCADE,
+  "position_rkey" text NOT NULL,
+  "skill_rkey" text NOT NULL,
+  "indexed_at" timestamp with time zone NOT NULL DEFAULT now(),
+  PRIMARY KEY ("did", "position_rkey", "skill_rkey")
+);
+
+ALTER TABLE "skills" ADD COLUMN IF NOT EXISTS "canonical_skill_id" uuid REFERENCES "canonical_skills"("id");

drizzle/meta/_journal.json

···
       "when": 1773712800000,
       "tag": "0011_add_country_code",
       "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "7",
+      "when": 1773799200000,
+      "tag": "0012_canonical_skills",
+      "breakpoints": true
     }
   ]
 }

src/db/schema/canonical-skills.ts

···
+import { pgTable, text, integer, uuid } from 'drizzle-orm/pg-core';
+
+export const canonicalSkills = pgTable('canonical_skills', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  canonicalName: text('canonical_name').notNull().unique(),
+  slug: text('slug').notNull().unique(),
+  category: text('category'),
+  subcategory: text('subcategory'),
+  aliases: text('aliases').array().notNull().default([]),
+  wikidataId: text('wikidata_id'),
+  userCount: integer('user_count').notNull().default(0),
+});

src/db/schema/index.ts

···
 export { languages } from './languages.js';
 export { suggestionDismissals } from './suggestion-dismissals.js';
 export { invites } from './invites.js';
+export { canonicalSkills } from './canonical-skills.js';
+export { unresolvedSkills } from './unresolved-skills.js';
+export { skillPositionLinks } from './skill-position-links.js';

src/db/schema/skill-position-links.ts

···
+import { pgTable, text, timestamp, primaryKey } from 'drizzle-orm/pg-core';
+import { profiles } from './profiles.js';
+
+export const skillPositionLinks = pgTable(
+  'skill_position_links',
+  {
+    did: text('did')
+      .notNull()
+      .references(() => profiles.did, { onDelete: 'cascade' }),
+    positionRkey: text('position_rkey').notNull(),
+    skillRkey: text('skill_rkey').notNull(),
+    indexedAt: timestamp('indexed_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [primaryKey({ columns: [table.did, table.positionRkey, table.skillRkey] })],
+);

src/db/schema/skills.ts

···
-import { pgTable, text, timestamp, primaryKey } from 'drizzle-orm/pg-core';
+import { pgTable, text, timestamp, primaryKey, uuid } from 'drizzle-orm/pg-core';
 import { profiles } from './profiles.js';
+import { canonicalSkills } from './canonical-skills.js';
 
 export const skills = pgTable(
   'skills',
···
     rkey: text('rkey').notNull(),
     skillName: text('skill_name').notNull(),
     category: text('category'),
+    canonicalSkillId: uuid('canonical_skill_id').references(() => canonicalSkills.id),
     createdAt: timestamp('created_at', { withTimezone: true }).notNull(),
     indexedAt: timestamp('indexed_at', { withTimezone: true }).notNull().defaultNow(),
   },

src/db/schema/unresolved-skills.ts

···
+import { pgTable, uuid, text, integer, timestamp } from 'drizzle-orm/pg-core';
+import { canonicalSkills } from './canonical-skills.js';
+
+export const unresolvedSkills = pgTable('unresolved_skills', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  rawName: text('raw_name').notNull(),
+  normalizedName: text('normalized_name').notNull().unique(),
+  occurrences: integer('occurrences').notNull().default(1),
+  firstSeenAt: timestamp('first_seen_at', { withTimezone: true }).notNull().defaultNow(),
+  resolvedAt: timestamp('resolved_at', { withTimezone: true }),
+  resolvedToId: uuid('resolved_to_id').references(() => canonicalSkills.id),
+});

src/jetstream/indexers/position.ts

···
 import type { Database } from '../../db/index.js';
-import { positions } from '../../db/schema/index.js';
+import { positions, skillPositionLinks } from '../../db/schema/index.js';
 import { and, eq } from 'drizzle-orm';
 import type { JetstreamEvent } from '../types.js';
 import { logger } from '../../logger.js';
 import { sanitize, sanitizeOptional } from '../../lib/sanitize.js';
 
+interface StrongRef {
+  uri: string;
+  cid: string;
+}
+
+/** Extract rkey from an AT Protocol URI: at://did/collection/rkey */
+function parseRkeyFromUri(uri: string): string | null {
+  const parts = uri.split('/');
+  return parts.length >= 5 ? (parts[4] ?? null) : null;
+}
+
 interface RecordLocation {
   country?: string;
   region?: string;
···
     const { operation, rkey, record } = commit;
 
     if (operation === 'delete') {
+      await db
+        .delete(skillPositionLinks)
+        .where(and(eq(skillPositionLinks.did, did), eq(skillPositionLinks.positionRkey, rkey)));
       await db.delete(positions).where(and(eq(positions.did, did), eq(positions.rkey, rkey)));
       logger.info({ did, rkey }, 'Deleted position');
       return;
···
         },
       });
 
-    logger.info({ did, rkey, operation }, 'Indexed position');
+    // Sync skill-position links: delete-and-replace strategy
+    await db
+      .delete(skillPositionLinks)
+      .where(and(eq(skillPositionLinks.did, did), eq(skillPositionLinks.positionRkey, rkey)));
+
+    const skillRefs = record.skills as StrongRef[] | undefined;
+    if (skillRefs && Array.isArray(skillRefs) && skillRefs.length > 0) {
+      const linkValues = skillRefs
+        .map((ref) => {
+          const skillRkey = parseRkeyFromUri(ref.uri);
+          if (!skillRkey) {
+            logger.warn(
+              { did, rkey, uri: ref.uri },
+              'Could not parse skill rkey from strongRef URI',
+            );
+            return null;
+          }
+          return { did, positionRkey: rkey, skillRkey };
+        })
+        .filter((v): v is NonNullable<typeof v> => v !== null);
+
+      if (linkValues.length > 0) {
+        await db.insert(skillPositionLinks).values(linkValues).onConflictDoNothing();
+      }
+    }
+
+    logger.info({ did, rkey, operation, skillLinks: skillRefs?.length ?? 0 }, 'Indexed position');
   };
 }

src/jetstream/indexers/skill.ts

···
 import type { Database } from '../../db/index.js';
-import { skills } from '../../db/schema/index.js';
-import { and, eq } from 'drizzle-orm';
+import { skills, canonicalSkills } from '../../db/schema/index.js';
+import { and, eq, sql } from 'drizzle-orm';
 import type { JetstreamEvent } from '../types.js';
 import { logger } from '../../logger.js';
 import { sanitize, sanitizeOptional } from '../../lib/sanitize.js';
+import { resolveSkill } from '../../services/skill-normalization.js';
 
 export function createSkillIndexer(db: Database) {
   return async (event: JetstreamEvent) => {
···
     const { operation, rkey, record } = commit;
 
     if (operation === 'delete') {
+      // Look up canonical_skill_id before deleting so we can decrement user_count
+      const existing = await db
+        .select({ canonicalSkillId: skills.canonicalSkillId })
+        .from(skills)
+        .where(and(eq(skills.did, did), eq(skills.rkey, rkey)))
+        .limit(1);
+
       await db.delete(skills).where(and(eq(skills.did, did), eq(skills.rkey, rkey)));
+
+      if (existing[0]?.canonicalSkillId) {
+        await db
+          .update(canonicalSkills)
+          .set({ userCount: sql`GREATEST(${canonicalSkills.userCount} - 1, 0)` })
+          .where(eq(canonicalSkills.id, existing[0].canonicalSkillId));
+      }
+
       logger.info({ did, rkey }, 'Deleted skill');
       return;
     }
 
     if (!record) return;
 
+    const skillName = sanitize(record.skillName as string);
+    const category = sanitizeOptional(record.category as string | undefined) ?? null;
+
+    // Run normalization pipeline
+    const canonical = await resolveSkill(db, skillName);
+    const canonicalSkillId = canonical?.id ?? null;
+
+    // Check if this is an update (existing record may already be linked to a different canonical)
+    const existing = await db
+      .select({ canonicalSkillId: skills.canonicalSkillId })
+      .from(skills)
+      .where(and(eq(skills.did, did), eq(skills.rkey, rkey)))
+      .limit(1);
+
+    const previousCanonicalId = existing[0]?.canonicalSkillId ?? null;
+
     await db
       .insert(skills)
       .values({
         did,
         rkey,
-        skillName: sanitize(record.skillName as string),
-        category: sanitizeOptional(record.category as string | undefined) ?? null,
+        skillName,
+        category,
+        canonicalSkillId,
         createdAt: new Date(record.createdAt as string),
         indexedAt: new Date(),
       })
       .onConflictDoUpdate({
         target: [skills.did, skills.rkey],
         set: {
-          skillName: sanitize(record.skillName as string),
-          category: sanitizeOptional(record.category as string | undefined) ?? null,
+          skillName,
+          category,
+          canonicalSkillId,
           indexedAt: new Date(),
         },
       });
 
-    logger.info({ did, rkey, operation }, 'Indexed skill');
+    // Update user_count: decrement old canonical (if changed), increment new
+    if (previousCanonicalId && previousCanonicalId !== canonicalSkillId) {
+      await db
+        .update(canonicalSkills)
+        .set({ userCount: sql`GREATEST(${canonicalSkills.userCount} - 1, 0)` })
+        .where(eq(canonicalSkills.id, previousCanonicalId));
+    }
+    if (canonicalSkillId && canonicalSkillId !== previousCanonicalId) {
+      await db
+        .update(canonicalSkills)
+        .set({ userCount: sql`${canonicalSkills.userCount} + 1` })
+        .where(eq(canonicalSkills.id, canonicalSkillId));
+    }
+
+    logger.info({ did, rkey, operation, canonicalSkillId }, 'Indexed skill');
   };
 }

src/routes/profile.ts

···
   externalAccounts,
   externalAccountVerifications,
   invites,
+  skillPositionLinks,
 } from '../db/schema/index.js';
 import { resolveSessionDid } from '../middleware/auth.js';
 import { isVerifiablePlatform } from '../services/verification.js';
···
         profileLanguages,
         profileExternalAccounts,
         verifications,
+        profileSkillPositionLinks,
       ] = await Promise.all([
         db.select().from(positions).where(eq(positions.did, profile.did)),
         db.select().from(education).where(eq(education.did, profile.did)),
···
           .select()
           .from(externalAccountVerifications)
           .where(eq(externalAccountVerifications.did, profile.did)),
+        db.select().from(skillPositionLinks).where(eq(skillPositionLinks.did, profile.did)),
       ]);
 
       const resolved = resolveProfileFields(
···
       ].filter(Boolean);
       const location = locationParts.length > 0 ? locationParts.join(', ') : null;
 
+      // Build skill-position link lookup maps
+      const linksBySkill = new Map<string, string[]>();
+      const linksByPosition = new Map<string, string[]>();
+      for (const link of profileSkillPositionLinks) {
+        const skillList = linksBySkill.get(link.skillRkey) ?? [];
+        skillList.push(link.positionRkey);
+        linksBySkill.set(link.skillRkey, skillList);
+
+        const posList = linksByPosition.get(link.positionRkey) ?? [];
+        posList.push(link.skillRkey);
+        linksByPosition.set(link.positionRkey, posList);
+      }
+
       // Find primary external account for website display
       const [primaryAccount] = await db
         .select()
···
           startDate: p.startDate,
           endDate: p.endDate,
           current: p.current,
+          skillRkeys: linksByPosition.get(p.rkey) ?? [],
         })),
         education: profileEducation.map((e) => ({
           rkey: e.rkey,
···
           rkey: s.rkey,
           skillName: s.skillName,
           category: s.category,
+          positionRkeys: linksBySkill.get(s.rkey) ?? [],
         })),
         certifications: profileCertifications.map((c) => ({
           rkey: c.rkey,

src/routes/skills.ts

···
+import type { FastifyInstance } from 'fastify';
+import type { Database } from '../db/index.js';
+import { sql } from 'drizzle-orm';
+
+export function registerSkillsRoutes(app: FastifyInstance, db: Database) {
+  app.get('/api/skills/search', async (request, reply) => {
+    const { q, limit = '20' } = request.query as Record<string, string>;
+    if (!q?.trim()) {
+      return reply
+        .status(400)
+        .send({ error: 'InvalidRequest', message: 'Query parameter q is required' });
+    }
+
+    const limitNum = Math.min(parseInt(limit, 10) || 20, 100);
+    const searchTerm = q.trim().toLowerCase();
+
+    // Search canonical_name with pg_trgm similarity + alias array matching
+    // Order by similarity score first, then user_count for tie-breaking
+    const results = await db.execute(sql`
+      SELECT id, canonical_name, slug, category, user_count,
+        GREATEST(
+          similarity(lower(canonical_name), ${searchTerm}),
+          (SELECT COALESCE(MAX(similarity(alias, ${searchTerm})), 0)
+           FROM unnest(aliases) AS alias)
+        ) AS sim
+      FROM canonical_skills
+      WHERE lower(canonical_name) % ${searchTerm}
+         OR canonical_name ILIKE ${'%' + searchTerm + '%'}
+         OR EXISTS (
+           SELECT 1 FROM unnest(aliases) AS alias
+           WHERE alias % ${searchTerm} OR alias ILIKE ${'%' + searchTerm + '%'}
+         )
+      ORDER BY sim DESC, user_count DESC
+      LIMIT ${limitNum}
+    `);
+
+    return {
+      skills: results.rows.map((row) => {
+        const r = row as Record<string, unknown>;
+        return {
+          id: r.id,
+          canonicalName: r.canonical_name,
+          slug: r.slug,
+          category: r.category,
+          userCount: r.user_count,
+        };
+      }),
+    };
+  });
+}

src/server.ts

···
 import { registerImportRoutes } from './routes/import.js';
 import { registerFollowRoutes } from './routes/follow.js';
 import { registerSearchRoutes } from './routes/search.js';
+import { registerSkillsRoutes } from './routes/skills.js';
 import { registerExternalAccountRoutes } from './routes/external-accounts.js';
 import { registerSuggestionRoutes } from './routes/suggestions.js';
 import { registerWellKnownRoutes } from './routes/well-known.js';
···
   registerImportRoutes(app, db, oauthClient);
   registerFollowRoutes(app, db, oauthClient);
   registerSearchRoutes(app, db);
+  registerSkillsRoutes(app, db);
   registerExternalAccountRoutes(app, db, oauthClient, valkey);
   registerSuggestionRoutes(app, db, oauthClient, config.PUBLIC_URL);
 

src/services/skill-normalization.ts

···
+import type { Database } from '../db/index.js';
+import { canonicalSkills, unresolvedSkills } from '../db/schema/index.js';
+import { eq, sql } from 'drizzle-orm';
+import { logger } from '../logger.js';
+
+/** Normalize a skill name for matching: lowercase, trim, collapse whitespace */
+export function normalizeSkillName(name: string): string {
+  return name.toLowerCase().trim().replace(/\s+/g, ' ');
+}
+
+/** Create a URL-safe slug from a skill name */
+export function createSlug(name: string): string {
+  return name
+    .toLowerCase()
+    .trim()
+    .replace(/c\+\+/gi, 'c-plus-plus')
+    .replace(/c#/gi, 'c-sharp')
+    .replace(/\.net/gi, 'dot-net')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+/**
+ * Resolve a user-entered skill name to a canonical skill.
+ * Pipeline: normalize -> check slug match -> check aliases -> queue as unresolved.
+ * Returns the canonical skill row if matched, null if unresolved.
+ */
+export async function resolveSkill(
+  db: Database,
+  rawName: string,
+): Promise<typeof canonicalSkills.$inferSelect | null> {
+  const normalized = normalizeSkillName(rawName);
+
+  // 1. Exact match on slug
+  const bySlug = await db
+    .select()
+    .from(canonicalSkills)
+    .where(eq(canonicalSkills.slug, createSlug(rawName)))
+    .limit(1);
+  if (bySlug[0]) {
+    return bySlug[0];
+  }
+
+  // 2. Check aliases array (any canonical_skills row where normalized name is in aliases)
+  const byAlias = await db
+    .select()
+    .from(canonicalSkills)
+    .where(sql`${normalized} = ANY(${canonicalSkills.aliases})`)
+    .limit(1);
+  if (byAlias[0]) {
+    return byAlias[0];
+  }
+
+  // 3. No match -- add to unresolved queue
+  await db
+    .insert(unresolvedSkills)
+    .values({
+      rawName,
+      normalizedName: normalized,
+    })
+    .onConflictDoUpdate({
+      target: unresolvedSkills.normalizedName,
+      set: {
+        occurrences: sql`${unresolvedSkills.occurrences} + 1`,
+      },
+    });
+
+  logger.info({ rawName, normalized }, 'Skill queued as unresolved');
+  return null;
+}

tests/db/schema-canonical-skills.test.ts

···
+import { describe, it, expect } from 'vitest';
+import { canonicalSkills } from '../../src/db/schema/index.js';
+
+describe('canonical_skills schema', () => {
+  it('has expected columns', () => {
+    expect(canonicalSkills.id).toBeDefined();
+    expect(canonicalSkills.canonicalName).toBeDefined();
+    expect(canonicalSkills.slug).toBeDefined();
+    expect(canonicalSkills.category).toBeDefined();
+    expect(canonicalSkills.subcategory).toBeDefined();
+    expect(canonicalSkills.aliases).toBeDefined();
+    expect(canonicalSkills.wikidataId).toBeDefined();
+    expect(canonicalSkills.userCount).toBeDefined();
+  });
+});

tests/db/schema-skill-position-links.test.ts

···
+import { describe, it, expect } from 'vitest';
+import { skillPositionLinks } from '../../src/db/schema/index.js';
+
+describe('skill_position_links schema', () => {
+  it('has expected columns', () => {
+    expect(skillPositionLinks.did).toBeDefined();
+    expect(skillPositionLinks.positionRkey).toBeDefined();
+    expect(skillPositionLinks.skillRkey).toBeDefined();
+    expect(skillPositionLinks.indexedAt).toBeDefined();
+  });
+});

tests/db/schema-unresolved-skills.test.ts

···
+import { describe, it, expect } from 'vitest';
+import { unresolvedSkills } from '../../src/db/schema/index.js';
+
+describe('unresolved_skills schema', () => {
+  it('has expected columns', () => {
+    expect(unresolvedSkills.id).toBeDefined();
+    expect(unresolvedSkills.rawName).toBeDefined();
+    expect(unresolvedSkills.normalizedName).toBeDefined();
+    expect(unresolvedSkills.occurrences).toBeDefined();
+    expect(unresolvedSkills.firstSeenAt).toBeDefined();
+    expect(unresolvedSkills.resolvedAt).toBeDefined();
+    expect(unresolvedSkills.resolvedToId).toBeDefined();
+  });
+});

tests/jetstream/position-indexer-skills.test.ts

···
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { createDb } from '../../src/db/index.js';
+import { positions, profiles, skills, skillPositionLinks } from '../../src/db/schema/index.js';
+import { createPositionIndexer } from '../../src/jetstream/indexers/position.js';
+import { eq, and, sql } from 'drizzle-orm';
+
+describe('Position indexer skill-position links', () => {
+  const db = createDb(process.env.DATABASE_URL ?? 'postgresql://sifa:sifa@localhost:5432/sifa');
+  const testDid = 'did:plc:pos-skill-link-test';
+
+  beforeAll(async () => {
+    await db
+      .insert(profiles)
+      .values({
+        did: testDid,
+        handle: 'pos-skill-test.bsky.social',
+        createdAt: new Date(),
+      })
+      .onConflictDoNothing();
+
+    await db
+      .insert(skills)
+      .values({
+        did: testDid,
+        rkey: '3skill1',
+        skillName: 'TypeScript',
+        createdAt: new Date(),
+      })
+      .onConflictDoNothing();
+
+    await db
+      .insert(skills)
+      .values({
+        did: testDid,
+        rkey: '3skill2',
+        skillName: 'PostgreSQL',
+        createdAt: new Date(),
+      })
+      .onConflictDoNothing();
+  });
+
+  afterAll(async () => {
+    await db.execute(sql`DELETE FROM skill_position_links WHERE did = ${testDid}`);
+    await db.delete(positions).where(eq(positions.did, testDid));
+    await db.delete(skills).where(eq(skills.did, testDid));
+    await db.execute(sql`DELETE FROM profiles WHERE did = ${testDid}`);
+    await db.$client.end();
+  });
+
+  it('creates skill-position links from position skills array', async () => {
+    const indexer = createPositionIndexer(db);
+    await indexer({
+      did: testDid,
+      time_us: 1234567890,
+      kind: 'commit',
+      commit: {
+        rev: 'rev1',
+        operation: 'create',
+        collection: 'id.sifa.profile.position',
+        rkey: '3pos1',
+        record: {
+          companyName: 'Acme',
+          title: 'Engineer',
+          startDate: '2024-01',
+          current: true,
+          createdAt: '2026-01-01T00:00:00Z',
+          skills: [
+            { uri: `at://${testDid}/id.sifa.profile.skill/3skill1`, cid: 'bafyabc1' },
+            { uri: `at://${testDid}/id.sifa.profile.skill/3skill2`, cid: 'bafyabc2' },
+          ],
+        },
+      },
+    });
+
+    const links = await db
+      .select()
+      .from(skillPositionLinks)
+      .where(
+        and(eq(skillPositionLinks.did, testDid), eq(skillPositionLinks.positionRkey, '3pos1')),
+      );
+    expect(links).toHaveLength(2);
+    expect(links.map((l) => l.skillRkey).sort()).toEqual(['3skill1', '3skill2']);
+  });
+
+  it('replaces links on position update', async () => {
+    const indexer = createPositionIndexer(db);
+    await indexer({
+      did: testDid,
+      time_us: 1234567891,
+      kind: 'commit',
+      commit: {
+        rev: 'rev2',
+        operation: 'update',
+        collection: 'id.sifa.profile.position',
+        rkey: '3pos1',
+        record: {
+          companyName: 'Acme',
+          title: 'Senior Engineer',
+          startDate: '2024-01',
+          current: true,
+          createdAt: '2026-01-01T00:00:00Z',
+          skills: [{ uri: `at://${testDid}/id.sifa.profile.skill/3skill1`, cid: 'bafyabc1' }],
+        },
+      },
+    });
+
+    const links = await db
+      .select()
+      .from(skillPositionLinks)
+      .where(
+        and(eq(skillPositionLinks.did, testDid), eq(skillPositionLinks.positionRkey, '3pos1')),
+      );
+    expect(links).toHaveLength(1);
+    expect(links[0].skillRkey).toBe('3skill1');
+  });
+
+  it('removes all links on position delete', async () => {
+    const indexer = createPositionIndexer(db);
+    await indexer({
+      did: testDid,
+      time_us: 1234567892,
+      kind: 'commit',
+      commit: {
+        rev: 'rev3',
+        operation: 'delete',
+        collection: 'id.sifa.profile.position',
+        rkey: '3pos1',
+      },
+    });
+
+    const links = await db
+      .select()
+      .from(skillPositionLinks)
+      .where(
+        and(eq(skillPositionLinks.did, testDid), eq(skillPositionLinks.positionRkey, '3pos1')),
+      );
+    expect(links).toHaveLength(0);
+  });
+
+  it('handles position with no skills array gracefully', async () => {
+    const indexer = createPositionIndexer(db);
+    await indexer({
+      did: testDid,
+      time_us: 1234567893,
+      kind: 'commit',
+      commit: {
+        rev: 'rev4',
+        operation: 'create',
+        collection: 'id.sifa.profile.position',
+        rkey: '3pos2',
+        record: {
+          companyName: 'Other Corp',
+          title: 'Dev',
+          startDate: '2025-01',
+          current: false,
+          createdAt: '2026-01-01T00:00:00Z',
+        },
+      },
+    });
+
+    const links = await db
+      .select()
+      .from(skillPositionLinks)
+      .where(
+        and(eq(skillPositionLinks.did, testDid), eq(skillPositionLinks.positionRkey, '3pos2')),
+      );
+    expect(links).toHaveLength(0);
+  });
+});

tests/jetstream/skill-indexer.test.ts

···
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { createDb } from '../../src/db/index.js';
+import { skills, canonicalSkills, profiles } from '../../src/db/schema/index.js';
+import { createSkillIndexer } from '../../src/jetstream/indexers/skill.js';
+import { eq, and, sql } from 'drizzle-orm';
+
+describe('Skill indexer with normalization', () => {
+  const db = createDb(process.env.DATABASE_URL ?? 'postgresql://sifa:sifa@localhost:5432/sifa');
+  const testDid = 'did:plc:skill-indexer-test';
+
+  beforeAll(async () => {
+    await db
+      .insert(profiles)
+      .values({
+        did: testDid,
+        handle: 'skill-test.bsky.social',
+        createdAt: new Date(),
+      })
+      .onConflictDoNothing();
+
+    await db
+      .insert(canonicalSkills)
+      .values({
+        canonicalName: 'TypeScript',
+        slug: 'typescript',
+        category: 'technical',
+        aliases: ['ts', 'typescript'],
+        userCount: 0,
+      })
+      .onConflictDoNothing();
+  });
+
+  afterAll(async () => {
+    await db.delete(skills).where(eq(skills.did, testDid));
+    await db.execute(sql`DELETE FROM canonical_skills WHERE slug = 'typescript'`);
+    await db.execute(sql`DELETE FROM unresolved_skills WHERE normalized_name = 'ts'`);
+    await db.execute(sql`DELETE FROM profiles WHERE did = ${testDid}`);
+    await db.$client.end();
+  });
+
+  it('indexes skill and resolves to canonical entry', async () => {
+    const indexer = createSkillIndexer(db);
+    await indexer({
+      did: testDid,
+      time_us: 1234567890,
+      kind: 'commit',
+      commit: {
+        rev: 'rev1',
+        operation: 'create',
+        collection: 'id.sifa.profile.skill',
+        rkey: '3skilltest1',
+        record: {
+          skillName: 'TS',
+          category: 'technical',
+          createdAt: '2026-01-01T00:00:00Z',
+        },
+      },
+    });
+
+    const indexed = await db
+      .select()
+      .from(skills)
+      .where(and(eq(skills.did, testDid), eq(skills.rkey, '3skilltest1')));
+    expect(indexed).toHaveLength(1);
+    expect(indexed[0].skillName).toBe('TS');
+    expect(indexed[0].canonicalSkillId).toBeDefined();
+    expect(indexed[0].canonicalSkillId).not.toBeNull();
+  });
+
+  it('increments user_count on canonical skill when resolved', async () => {
+    const canonical = await db
+      .select()
+      .from(canonicalSkills)
+      .where(eq(canonicalSkills.slug, 'typescript'));
+    expect(canonical[0].userCount).toBeGreaterThanOrEqual(1);
+  });
+
+  it('deletes skill and decrements user_count', async () => {
+    const indexer = createSkillIndexer(db);
+    await indexer({
+      did: testDid,
+      time_us: 1234567891,
+      kind: 'commit',
+      commit: {
+        rev: 'rev2',
+        operation: 'delete',
+        collection: 'id.sifa.profile.skill',
+        rkey: '3skilltest1',
+      },
+    });
+
+    const indexed = await db
+      .select()
+      .from(skills)
+      .where(and(eq(skills.did, testDid), eq(skills.rkey, '3skilltest1')));
+    expect(indexed).toHaveLength(0);
+  });
+});

tests/routes/profile-skill-links.test.ts

···
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { buildServer } from '../../src/server.js';
+import { createDb } from '../../src/db/index.js';
+import { profiles, positions, skills, skillPositionLinks } from '../../src/db/schema/index.js';
+import { sql } from 'drizzle-orm';
+import { writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { FastifyInstance } from 'fastify';
+
+describe('Profile API -- skill-position links', () => {
+  let app: FastifyInstance;
+  const db = createDb(process.env.DATABASE_URL ?? 'postgresql://sifa:sifa@localhost:5432/sifa');
+  const tmpKeysDir = join(tmpdir(), `sifa-test-keys-profile-skills-${Date.now()}`);
+  const jwksPath = join(tmpKeysDir, 'jwks.json');
+  const testDid = 'did:plc:profile-skill-link-test';
+
+  beforeAll(async () => {
+    mkdirSync(tmpKeysDir, { recursive: true });
+    writeFileSync(jwksPath, JSON.stringify({ keys: [{ kty: 'EC', crv: 'P-256', kid: 'test' }] }));
+
+    await db
+      .insert(profiles)
+      .values({
+        did: testDid,
+        handle: 'skill-link-profile.bsky.social',
+        headline: 'Test Profile',
+        createdAt: new Date(),
+      })
+      .onConflictDoNothing();
+
+    await db
+      .insert(positions)
+      .values({
+        did: testDid,
+        rkey: '3pos1',
+        companyName: 'Acme',
+        title: 'Engineer',
+        startDate: '2024-01',
+        current: true,
+        createdAt: new Date(),
+      })
+      .onConflictDoNothing();
+
+    await db
+      .insert(skills)
+      .values({
+        did: testDid,
+        rkey: '3skill1',
+        skillName: 'TypeScript',
+        category: 'technical',
+        createdAt: new Date(),
+      })
+      .onConflictDoNothing();
+
+    await db
+      .insert(skillPositionLinks)
+      .values({
+        did: testDid,
+        positionRkey: '3pos1',
+        skillRkey: '3skill1',
+      })
+      .onConflictDoNothing();
+
+    app = await buildServer({
+      NODE_ENV: 'test',
+      PORT: 0,
+      PUBLIC_URL: 'http://localhost:3100',
+      DATABASE_URL: process.env.DATABASE_URL ?? 'postgresql://sifa:sifa@localhost:5432/sifa',
+      VALKEY_URL: 'redis://localhost:6379',
+      SIFA_DID: 'did:plc:test',
+      JETSTREAM_URL: 'wss://jetstream1.us-east.bsky.network/subscribe',
+      OAUTH_JWKS_PATH: jwksPath,
+    });
+  });
+
+  afterAll(async () => {
+    await db.execute(sql`DELETE FROM skill_position_links WHERE did = ${testDid}`);
+    await db.execute(sql`DELETE FROM positions WHERE did = ${testDid}`);
+    await db.execute(sql`DELETE FROM skills WHERE did = ${testDid}`);
+    await db.execute(sql`DELETE FROM profiles WHERE did = ${testDid}`);
+    await db.$client.end();
+    await app.close();
+    rmSync(tmpKeysDir, { recursive: true });
+  });
+
+  it('includes positionRkeys on skills in profile response', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: `/api/profile/${testDid}`,
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    const skill = body.skills.find((s: { rkey: string }) => s.rkey === '3skill1');
+    expect(skill).toBeDefined();
+    expect(skill.positionRkeys).toEqual(['3pos1']);
+  });
+
+  it('includes skillRkeys on positions in profile response', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: `/api/profile/${testDid}`,
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    const position = body.positions.find((p: { rkey: string }) => p.rkey === '3pos1');
+    expect(position).toBeDefined();
+    expect(position.skillRkeys).toEqual(['3skill1']);
+  });
+});

tests/routes/skills.test.ts

···
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { buildServer } from '../../src/server.js';
+import { createDb } from '../../src/db/index.js';
+import { canonicalSkills } from '../../src/db/schema/index.js';
+import { sql } from 'drizzle-orm';
+import { writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { FastifyInstance } from 'fastify';
+
+describe('Skills Search API', () => {
+  let app: FastifyInstance;
+  const db = createDb(process.env.DATABASE_URL ?? 'postgresql://sifa:sifa@localhost:5432/sifa');
+  const tmpKeysDir = join(tmpdir(), `sifa-test-keys-skills-${Date.now()}`);
+  const jwksPath = join(tmpKeysDir, 'jwks.json');
+
+  beforeAll(async () => {
+    mkdirSync(tmpKeysDir, { recursive: true });
+    writeFileSync(jwksPath, JSON.stringify({ keys: [{ kty: 'EC', crv: 'P-256', kid: 'test' }] }));
+
+    // Ensure the table exists (migration may not have run in test mode)
+    await db.execute(sql`
+      CREATE TABLE IF NOT EXISTS "canonical_skills" (
+        "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+        "canonical_name" text NOT NULL UNIQUE,
+        "slug" text NOT NULL UNIQUE,
+        "category" text,
+        "subcategory" text,
+        "aliases" text[] NOT NULL DEFAULT '{}',
+        "wikidata_id" text,
+        "user_count" integer NOT NULL DEFAULT 0
+      )
+    `);
+
+    // Seed canonical skills for search
+    await db
+      .insert(canonicalSkills)
+      .values([
+        {
+          canonicalName: 'JavaScript',
+          slug: 'javascript',
+          category: 'technical',
+          aliases: ['js', 'javascript'],
+          userCount: 150,
+        },
+        {
+          canonicalName: 'TypeScript',
+          slug: 'typescript',
+          category: 'technical',
+          aliases: ['ts', 'typescript'],
+          userCount: 120,
+        },
+        {
+          canonicalName: 'Java',
+          slug: 'java',
+          category: 'technical',
+          aliases: ['java'],
+          userCount: 80,
+        },
+        {
+          canonicalName: 'Python',
+          slug: 'python',
+          category: 'technical',
+          aliases: ['python', 'py'],
+          userCount: 200,
+        },
+        {
+          canonicalName: 'Project Management',
+          slug: 'project-management',
+          category: 'business',
+          aliases: ['project management', 'pm'],
+          userCount: 50,
+        },
+      ])
+      .onConflictDoNothing();
+
+    app = await buildServer({
+      NODE_ENV: 'test',
+      PORT: 0,
+      PUBLIC_URL: 'http://localhost:3100',
+      DATABASE_URL: process.env.DATABASE_URL ?? 'postgresql://sifa:sifa@localhost:5432/sifa',
+      VALKEY_URL: 'redis://localhost:6379',
+      SIFA_DID: 'did:plc:test',
+      JETSTREAM_URL: 'wss://jetstream1.us-east.bsky.network/subscribe',
+      OAUTH_JWKS_PATH: jwksPath,
+    });
+  });
+
+  afterAll(async () => {
+    await db.execute(
+      sql`DELETE FROM canonical_skills WHERE slug IN ('javascript', 'typescript', 'java', 'python', 'project-management')`,
+    );
+    await db.$client.end();
+    await app.close();
+    rmSync(tmpKeysDir, { recursive: true });
+  });
+
+  it('GET /api/skills/search returns matching skills ordered by similarity and user_count', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/skills/search?q=java' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.skills.length).toBeGreaterThanOrEqual(2);
+    const names = body.skills.map((s: { canonicalName: string }) => s.canonicalName);
+    expect(names).toContain('JavaScript');
+    expect(names).toContain('Java');
+  });
+
+  it('GET /api/skills/search returns 400 without query', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/skills/search' });
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('GET /api/skills/search returns empty for no matches', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/skills/search?q=xyznonexistent999' });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().skills).toHaveLength(0);
+  });
+
+  it('GET /api/skills/search respects limit parameter', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/skills/search?q=java&limit=1' });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().skills).toHaveLength(1);
+  });
+
+  it('GET /api/skills/search includes category and user_count', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/skills/search?q=python' });
+    const body = res.json();
+    const python = body.skills.find((s: { canonicalName: string }) => s.canonicalName === 'Python');
+    expect(python).toBeDefined();
+    expect(python.category).toBe('technical');
+    expect(python.userCount).toBe(200);
+    expect(python.slug).toBe('python');
+  });
+
+  it('GET /api/skills/search matches aliases', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/skills/search?q=pm' });
+    const body = res.json();
+    const pm = body.skills.find(
+      (s: { canonicalName: string }) => s.canonicalName === 'Project Management',
+    );
+    expect(pm).toBeDefined();
+  });
+});

tests/services/skill-normalization-db.test.ts

···
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { createDb } from '../../src/db/index.js';
+import { canonicalSkills, unresolvedSkills } from '../../src/db/schema/index.js';
+import { resolveSkill } from '../../src/services/skill-normalization.js';
+import { eq, sql } from 'drizzle-orm';
+
+describe('resolveSkill (integration)', () => {
+  const db = createDb(process.env.DATABASE_URL ?? 'postgresql://sifa:sifa@localhost:5432/sifa');
+
+  beforeAll(async () => {
+    await db
+      .insert(canonicalSkills)
+      .values({
+        canonicalName: 'JavaScript',
+        slug: 'javascript',
+        category: 'technical',
+        aliases: ['js', 'javascript', 'ecmascript', 'java script'],
+        userCount: 0,
+      })
+      .onConflictDoNothing();
+  });
+
+  afterAll(async () => {
+    await db.delete(canonicalSkills).where(eq(canonicalSkills.slug, 'javascript'));
+    await db.execute(
+      sql`DELETE FROM unresolved_skills WHERE normalized_name IN ('javascript', 'completely-unknown-skill-xyz')`,
+    );
+    await db.$client.end();
+  });
+
+  it('resolves an alias to canonical skill', async () => {
+    const result = await resolveSkill(db, 'JS');
+    expect(result).not.toBeNull();
+    expect(result?.canonicalName).toBe('JavaScript');
+    expect(result?.slug).toBe('javascript');
+  });
+
+  it('resolves exact canonical name', async () => {
+    const result = await resolveSkill(db, 'JavaScript');
+    expect(result).not.toBeNull();
+    expect(result?.canonicalName).toBe('JavaScript');
+  });
+
+  it('returns null and queues unresolved skill when no match found', async () => {
+    const result = await resolveSkill(db, 'completely-unknown-skill-xyz');
+    expect(result).toBeNull();
+
+    const unresolved = await db
+      .select()
+      .from(unresolvedSkills)
+      .where(eq(unresolvedSkills.normalizedName, 'completely-unknown-skill-xyz'));
+    expect(unresolved).toHaveLength(1);
+    expect(unresolved[0].occurrences).toBe(1);
+  });
+
+  it('increments occurrence count for repeated unresolved skills', async () => {
+    await resolveSkill(db, 'completely-unknown-skill-xyz');
+    const unresolved = await db
+      .select()
+      .from(unresolvedSkills)
+      .where(eq(unresolvedSkills.normalizedName, 'completely-unknown-skill-xyz'));
+    expect(unresolved[0].occurrences).toBe(2);
+  });
+});

tests/services/skill-normalization.test.ts

···
+import { describe, it, expect } from 'vitest';
+import { normalizeSkillName, createSlug } from '../../src/services/skill-normalization.js';
+
+describe('normalizeSkillName', () => {
+  it('lowercases and trims input', () => {
+    expect(normalizeSkillName('  React.js  ')).toBe('react.js');
+  });
+
+  it('handles mixed case', () => {
+    expect(normalizeSkillName('TypeScript')).toBe('typescript');
+  });
+
+  it('preserves dots and hyphens', () => {
+    expect(normalizeSkillName('Node.js')).toBe('node.js');
+    expect(normalizeSkillName('vue-router')).toBe('vue-router');
+  });
+
+  it('collapses multiple spaces', () => {
+    expect(normalizeSkillName('machine   learning')).toBe('machine learning');
+  });
+});
+
+describe('createSlug', () => {
+  it('creates url-safe slug from skill name', () => {
+    expect(createSlug('React.js')).toBe('react-js');
+  });
+
+  it('handles spaces and special chars', () => {
+    expect(createSlug('C++')).toBe('c-plus-plus');
+    expect(createSlug('C#')).toBe('c-sharp');
+  });
+
+  it('collapses multiple hyphens', () => {
+    expect(createSlug('Node.js / Express')).toBe('node-js-express');
+  });
+});