feat(core): works catalogue and matching

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

packages/core/src/matching.ts

@@ -0,0 +1,166 @@
+import { sql } from "kysely";
+import type { WorkHint } from "@sttracker/plugin-sdk/types";
+import type { Db } from "@sttracker/db/db";
+import { newId, nowIso } from "@sttracker/db/ids";
+import {
+  createWorkIn,
+  findWorkByExternalIdsIn,
+  normalizePosition,
+  resolveAliasIn,
+  toWork,
+  updateWorkFromHintIn,
+  type K,
+} from "./works.ts";
+
+export interface FuzzyInput {
+  title: string;
+  year?: number | null;
+  creators?: { name: string }[];
+}
+
+function normalize(s: string): string {
+  return s
+    .normalize("NFD")
+    .replace(/\p{M}+/gu, "")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .trim()
+    .replace(/^(the|a|an)\s+/, "");
+}
+
+function tokens(s: string): string[] {
+  return normalize(s).split(" ").filter(Boolean);
+}
+
+/**
+ * 0..1 similarity. Title token-set Jaccard weighs 0.7; year 0.2 (±1 year counts half); any shared
+ * creator 0.1. A component missing on either side is left out and the weights renormalised, so a
+ * title-only comparison can still reach 1.
+ */
+export function fuzzyScore(a: FuzzyInput, b: FuzzyInput): number {
+  const ta = new Set(tokens(a.title));
+  const tb = new Set(tokens(b.title));
+  let inter = 0;
+  for (const t of ta) if (tb.has(t)) inter++;
+  const union = ta.size + tb.size - inter;
+  const jaccard = union === 0 ? 0 : inter / union;
+  let score = jaccard * 0.7;
+  let weight = 0.7;
+  if (a.year != null && b.year != null) {
+    const d = Math.abs(a.year - b.year);
+    score += d === 0 ? 0.2 : d === 1 ? 0.1 : 0;
+    weight += 0.2;
+  }
+  const ca = new Set((a.creators ?? []).map((c) => normalize(c.name)).filter(Boolean));
+  const cb = (b.creators ?? []).map((c) => normalize(c.name)).filter(Boolean);
+  if (ca.size > 0 && cb.length > 0) {
+    if (cb.some((n) => ca.has(n))) score += 0.1;
+    weight += 0.1;
+  }
+  return score / weight;
+}
+
+interface Resolved {
+  workId: string;
+  created: boolean;
+  draft: boolean;
+}
+
+async function resolve(k: K, userId: string | null, hint: WorkHint, actor: string): Promise<Resolved> {
+  // 1. Any external ID.
+  const byId = await findWorkByExternalIdsIn(k, hint.externalIds);
+  if (byId) {
+    await updateWorkFromHintIn(k, byId, hint, actor);
+    const owner = await k.selectFrom("works").select("owner_user_id").where("id", "=", byId).executeTakeFirstOrThrow();
+    const workId = userId ? await resolveAliasIn(k, userId, byId) : byId;
+    return { workId, created: false, draft: owner.owner_user_id !== null };
+  }
+
+  // 2. Parent + position.
+  const parentId = hint.parent ? (await resolve(k, null, hint.parent, actor)).workId : null;
+  const position = normalizePosition(hint.position);
+  if (parentId && position) {
+    const child = await k
+      .selectFrom("works")
+      .select("id")
+      .where("parent_id", "=", parentId)
+      .where("position", "=", position)
+      .where("merged_into_id", "is", null)
+      .where("owner_user_id", "is", null)
+      .executeTakeFirst();
+    if (child) {
+      await updateWorkFromHintIn(k, child.id, hint, actor);
+      return { workId: child.id, created: false, draft: false };
+    }
+    return { workId: await createWorkIn(k, { hint, parentId }, actor), created: true, draft: false };
+  }
+
+  // 3. External IDs but no match: new shared work.
+  if (Object.keys(hint.externalIds).length > 0) {
+    return { workId: await createWorkIn(k, { hint, parentId }, actor), created: true, draft: false };
+  }
+
+  if (userId === null) {
+    // Parent of a shared child: reuse an identical shared work, else create one.
+    let q = k
+      .selectFrom("works")
+      .select("id")
+      .where("owner_user_id", "is", null)
+      .where("merged_into_id", "is", null)
+      .where("media_type", "=", hint.mediaType)
+      .where(sql<boolean>`lower(title) = ${hint.title.toLowerCase()}`);
+    q = hint.year === undefined ? q : q.where("year", "=", hint.year);
+    q = parentId ? q.where("parent_id", "=", parentId) : q.where("parent_id", "is", null);
+    const same = await q.executeTakeFirst();
+    if (same) return { workId: same.id, created: false, draft: false };
+    return { workId: await createWorkIn(k, { hint, parentId }, actor), created: true, draft: false };
+  }
+
+  // 4. Private draft plus fuzzy suggestions.
+  const workId = await createWorkIn(k, { hint, ownerUserId: userId }, actor);
+  await suggest(k, userId, workId, hint);
+  return { workId, created: true, draft: true };
+}
+
+async function suggest(k: K, userId: string, draftId: string, hint: WorkHint): Promise<void> {
+  // Bound the candidate set with LIKE on the significant title tokens (OR), so "The Expanse: Leviathan
+  // Wakes" still finds "Leviathan Wakes". Tokens of 3+ chars, first five; falls back to the first token.
+  const all = tokens(hint.title);
+  const sig = all.filter((t) => t.length >= 3).slice(0, 5);
+  const likeTokens = sig.length > 0 ? sig : all.slice(0, 1);
+  if (likeTokens.length === 0) return;
+  const rows = await k
+    .selectFrom("works")
+    .selectAll()
+    .where("merged_into_id", "is", null)
+    .where("id", "!=", draftId)
+    .where((eb) =>
+      eb.or([
+        eb.and([eb("owner_user_id", "is", null), eb("media_type", "=", hint.mediaType)]),
+        eb("owner_user_id", "=", userId),
+      ]),
+    )
+    .where((eb) =>
+      eb.or(likeTokens.map((t) => eb(sql<string>`lower(title)`, "like", `%${t}%`))),
+    )
+    .limit(200)
+    .execute();
+  const scored = rows
+    .map(toWork)
+    .map((w) => ({ id: w.id, score: fuzzyScore(hint, w) }))
+    .filter((c) => c.score >= 0.6)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, 5);
+  const now = nowIso();
+  for (const c of scored) {
+    await k
+      .insertInto("match_suggestions")
+      .values({ id: newId(), user_id: userId, work_id: draftId, candidate_work_id: c.id, score: c.score, status: "pending", created_at: now })
+      .execute();
+  }
+}
+
+/** Resolve a hint to a work per spec §8.4. Never auto-links on fuzzy matches; those become suggestions. */
+export function matchWork(db: Db, userId: string, hint: WorkHint, actor: string): Promise<Resolved> {
+  return db.k.transaction().execute((tx) => resolve(tx, userId, hint, actor));
+}