pilothub 0.0.1

package/convex/maintenance.ts

@@ -0,0 +1,840 @@
+import { ConvexError, v } from 'convex/values'
+import { internal } from './_generated/api'
+import type { Doc, Id } from './_generated/dataModel'
+import type { ActionCtx } from './_generated/server'
+import { action, internalAction, internalMutation, internalQuery } from './_generated/server'
+import { assertRole, requireUserFromAction } from './lib/access'
+import { buildSkillSummaryBackfillPatch, type ParsedSkillData } from './lib/skillBackfill'
+import { hashSkillFiles } from './lib/skills'
+
+const DEFAULT_BATCH_SIZE = 50
+const MAX_BATCH_SIZE = 200
+const DEFAULT_MAX_BATCHES = 20
+const MAX_MAX_BATCHES = 200
+
+type BackfillStats = {
+  skillsScanned: number
+  skillsPatched: number
+  versionsPatched: number
+  missingLatestVersion: number
+  missingReadme: number
+  missingStorageBlob: number
+}
+
+type BackfillPageItem =
+  | {
+      kind: 'ok'
+      skillId: Id<'skills'>
+      versionId: Id<'skillVersions'>
+      skillSummary: Doc<'skills'>['summary']
+      versionParsed: Doc<'skillVersions'>['parsed']
+      readmeStorageId: Id<'_storage'>
+    }
+  | { kind: 'missingLatestVersion'; skillId: Id<'skills'> }
+  | { kind: 'missingVersionDoc'; skillId: Id<'skills'>; versionId: Id<'skillVersions'> }
+  | { kind: 'missingReadme'; skillId: Id<'skills'>; versionId: Id<'skillVersions'> }
+
+type BackfillPageResult = {
+  items: BackfillPageItem[]
+  cursor: string | null
+  isDone: boolean
+}
+
+export const getSkillBackfillPageInternal = internalQuery({
+  args: {
+    cursor: v.optional(v.string()),
+    batchSize: v.optional(v.number()),
+  },
+  handler: async (ctx, args): Promise<BackfillPageResult> => {
+    const batchSize = clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE)
+    const { page, isDone, continueCursor } = await ctx.db
+      .query('skills')
+      .order('asc')
+      .paginate({ cursor: args.cursor ?? null, numItems: batchSize })
+
+    const items: BackfillPageItem[] = []
+    for (const skill of page) {
+      if (!skill.latestVersionId) {
+        items.push({ kind: 'missingLatestVersion', skillId: skill._id })
+        continue
+      }
+
+      const version = await ctx.db.get(skill.latestVersionId)
+      if (!version) {
+        items.push({
+          kind: 'missingVersionDoc',
+          skillId: skill._id,
+          versionId: skill.latestVersionId,
+        })
+        continue
+      }
+
+      const readmeFile = version.files.find(
+        (file) => file.path.toLowerCase() === 'skill.md' || file.path.toLowerCase() === 'skills.md',
+      )
+      if (!readmeFile) {
+        items.push({ kind: 'missingReadme', skillId: skill._id, versionId: version._id })
+        continue
+      }
+
+      items.push({
+        kind: 'ok',
+        skillId: skill._id,
+        versionId: version._id,
+        skillSummary: skill.summary,
+        versionParsed: version.parsed,
+        readmeStorageId: readmeFile.storageId,
+      })
+    }
+
+    return { items, cursor: continueCursor, isDone }
+  },
+})
+
+export const applySkillBackfillPatchInternal = internalMutation({
+  args: {
+    skillId: v.id('skills'),
+    versionId: v.id('skillVersions'),
+    summary: v.optional(v.string()),
+    parsed: v.optional(
+      v.object({
+        frontmatter: v.record(v.string(), v.any()),
+        metadata: v.optional(v.any()),
+        pilotbot: v.optional(v.any()),
+      }),
+    ),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now()
+    if (typeof args.summary === 'string') {
+      await ctx.db.patch(args.skillId, { summary: args.summary, updatedAt: now })
+    }
+    if (args.parsed) {
+      await ctx.db.patch(args.versionId, { parsed: args.parsed })
+    }
+    return { ok: true as const }
+  },
+})
+
+export type BackfillActionArgs = {
+  dryRun?: boolean
+  batchSize?: number
+  maxBatches?: number
+}
+
+export type BackfillActionResult = { ok: true; stats: BackfillStats }
+
+export async function backfillSkillSummariesInternalHandler(
+  ctx: ActionCtx,
+  args: BackfillActionArgs,
+): Promise<BackfillActionResult> {
+  const dryRun = Boolean(args.dryRun)
+  const batchSize = clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE)
+  const maxBatches = clampInt(args.maxBatches ?? DEFAULT_MAX_BATCHES, 1, MAX_MAX_BATCHES)
+
+  const totals: BackfillStats = {
+    skillsScanned: 0,
+    skillsPatched: 0,
+    versionsPatched: 0,
+    missingLatestVersion: 0,
+    missingReadme: 0,
+    missingStorageBlob: 0,
+  }
+
+  let cursor: string | null = null
+  let isDone = false
+
+  for (let i = 0; i < maxBatches; i++) {
+    const page = (await ctx.runQuery(internal.maintenance.getSkillBackfillPageInternal, {
+      cursor: cursor ?? undefined,
+      batchSize,
+    })) as BackfillPageResult
+
+    cursor = page.cursor
+    isDone = page.isDone
+
+    for (const item of page.items) {
+      totals.skillsScanned++
+      if (item.kind === 'missingLatestVersion') {
+        totals.missingLatestVersion++
+        continue
+      }
+      if (item.kind === 'missingVersionDoc') {
+        totals.missingLatestVersion++
+        continue
+      }
+      if (item.kind === 'missingReadme') {
+        totals.missingReadme++
+        continue
+      }
+
+      const blob = await ctx.storage.get(item.readmeStorageId)
+      if (!blob) {
+        totals.missingStorageBlob++
+        continue
+      }
+
+      const readmeText = await blob.text()
+      const patch = buildSkillSummaryBackfillPatch({
+        readmeText,
+        currentSummary: item.skillSummary ?? undefined,
+        currentParsed: item.versionParsed as ParsedSkillData,
+      })
+
+      if (!patch.summary && !patch.parsed) continue
+      if (patch.summary) totals.skillsPatched++
+      if (patch.parsed) totals.versionsPatched++
+
+      if (dryRun) continue
+
+      await ctx.runMutation(internal.maintenance.applySkillBackfillPatchInternal, {
+        skillId: item.skillId,
+        versionId: item.versionId,
+        summary: patch.summary,
+        parsed: patch.parsed,
+      })
+    }
+
+    if (isDone) break
+  }
+
+  if (!isDone) {
+    throw new ConvexError('Backfill incomplete (maxBatches reached)')
+  }
+
+  return { ok: true as const, stats: totals }
+}
+
+export const backfillSkillSummariesInternal = internalAction({
+  args: {
+    dryRun: v.optional(v.boolean()),
+    batchSize: v.optional(v.number()),
+    maxBatches: v.optional(v.number()),
+  },
+  handler: backfillSkillSummariesInternalHandler,
+})
+
+export const backfillSkillSummaries: ReturnType<typeof action> = action({
+  args: {
+    dryRun: v.optional(v.boolean()),
+    batchSize: v.optional(v.number()),
+    maxBatches: v.optional(v.number()),
+  },
+  handler: async (ctx, args): Promise<BackfillActionResult> => {
+    const { user } = await requireUserFromAction(ctx)
+    assertRole(user, ['admin'])
+    return ctx.runAction(
+      internal.maintenance.backfillSkillSummariesInternal,
+      args,
+    ) as Promise<BackfillActionResult>
+  },
+})
+
+export const scheduleBackfillSkillSummaries: ReturnType<typeof action> = action({
+  args: { dryRun: v.optional(v.boolean()) },
+  handler: async (ctx, args) => {
+    const { user } = await requireUserFromAction(ctx)
+    assertRole(user, ['admin'])
+    await ctx.scheduler.runAfter(0, internal.maintenance.backfillSkillSummariesInternal, {
+      dryRun: Boolean(args.dryRun),
+      batchSize: DEFAULT_BATCH_SIZE,
+      maxBatches: DEFAULT_MAX_BATCHES,
+    })
+    return { ok: true as const }
+  },
+})
+
+type FingerprintBackfillStats = {
+  versionsScanned: number
+  versionsPatched: number
+  fingerprintsInserted: number
+  fingerprintMismatches: number
+}
+
+type FingerprintBackfillPageItem = {
+  skillId: Id<'skills'>
+  versionId: Id<'skillVersions'>
+  versionFingerprint?: string
+  files: Array<{ path: string; sha256: string }>
+  existingEntries: Array<{ id: Id<'skillVersionFingerprints'>; fingerprint: string }>
+}
+
+type FingerprintBackfillPageResult = {
+  items: FingerprintBackfillPageItem[]
+  cursor: string | null
+  isDone: boolean
+}
+
+type BadgeBackfillStats = {
+  skillsScanned: number
+  skillsPatched: number
+  highlightsPatched: number
+}
+
+type SkillBadgeTableBackfillStats = {
+  skillsScanned: number
+  recordsInserted: number
+}
+
+type BadgeBackfillPageItem = {
+  skillId: Id<'skills'>
+  ownerUserId: Id<'users'>
+  createdAt?: number
+  updatedAt?: number
+  batch?: string
+  badges?: Doc<'skills'>['badges']
+}
+
+type BadgeBackfillPageResult = {
+  items: BadgeBackfillPageItem[]
+  cursor: string | null
+  isDone: boolean
+}
+
+type BadgeKind = Doc<'skillBadges'>['kind']
+
+export const getSkillFingerprintBackfillPageInternal = internalQuery({
+  args: {
+    cursor: v.optional(v.string()),
+    batchSize: v.optional(v.number()),
+  },
+  handler: async (ctx, args): Promise<FingerprintBackfillPageResult> => {
+    const batchSize = clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE)
+    const { page, isDone, continueCursor } = await ctx.db
+      .query('skillVersions')
+      .order('asc')
+      .paginate({ cursor: args.cursor ?? null, numItems: batchSize })
+
+    const items: FingerprintBackfillPageItem[] = []
+    for (const version of page) {
+      const existingEntries = await ctx.db
+        .query('skillVersionFingerprints')
+        .withIndex('by_version', (q) => q.eq('versionId', version._id))
+        .take(20)
+
+      const normalizedFiles = version.files.map((file) => ({
+        path: file.path,
+        sha256: file.sha256,
+      }))
+
+      const hasAnyEntry = existingEntries.length > 0
+      const entryFingerprints = new Set(existingEntries.map((entry) => entry.fingerprint))
+      const hasFingerprintMismatch =
+        typeof version.fingerprint === 'string' &&
+        hasAnyEntry &&
+        (entryFingerprints.size !== 1 || !entryFingerprints.has(version.fingerprint))
+      const needsFingerprintField = !version.fingerprint
+      const needsFingerprintEntry = !hasAnyEntry
+
+      if (!needsFingerprintField && !needsFingerprintEntry && !hasFingerprintMismatch) continue
+
+      items.push({
+        skillId: version.skillId,
+        versionId: version._id,
+        versionFingerprint: version.fingerprint ?? undefined,
+        files: normalizedFiles,
+        existingEntries: existingEntries.map((entry) => ({
+          id: entry._id,
+          fingerprint: entry.fingerprint,
+        })),
+      })
+    }
+
+    return { items, cursor: continueCursor, isDone }
+  },
+})
+
+export const applySkillFingerprintBackfillPatchInternal = internalMutation({
+  args: {
+    versionId: v.id('skillVersions'),
+    fingerprint: v.string(),
+    patchVersion: v.boolean(),
+    replaceEntries: v.boolean(),
+    existingEntryIds: v.optional(v.array(v.id('skillVersionFingerprints'))),
+  },
+  handler: async (ctx, args) => {
+    const version = await ctx.db.get(args.versionId)
+    if (!version) return { ok: false as const, reason: 'missingVersion' as const }
+
+    const now = Date.now()
+
+    if (args.patchVersion) {
+      await ctx.db.patch(version._id, { fingerprint: args.fingerprint })
+    }
+
+    if (args.replaceEntries) {
+      const existing = args.existingEntryIds ?? []
+      for (const id of existing) {
+        await ctx.db.delete(id)
+      }
+
+      await ctx.db.insert('skillVersionFingerprints', {
+        skillId: version.skillId,
+        versionId: version._id,
+        fingerprint: args.fingerprint,
+        createdAt: now,
+      })
+    }
+
+    return { ok: true as const }
+  },
+})
+
+export type FingerprintBackfillActionArgs = {
+  dryRun?: boolean
+  batchSize?: number
+  maxBatches?: number
+}
+
+export type FingerprintBackfillActionResult = { ok: true; stats: FingerprintBackfillStats }
+
+export async function backfillSkillFingerprintsInternalHandler(
+  ctx: ActionCtx,
+  args: FingerprintBackfillActionArgs,
+): Promise<FingerprintBackfillActionResult> {
+  const dryRun = Boolean(args.dryRun)
+  const batchSize = clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE)
+  const maxBatches = clampInt(args.maxBatches ?? DEFAULT_MAX_BATCHES, 1, MAX_MAX_BATCHES)
+
+  const totals: FingerprintBackfillStats = {
+    versionsScanned: 0,
+    versionsPatched: 0,
+    fingerprintsInserted: 0,
+    fingerprintMismatches: 0,
+  }
+
+  let cursor: string | null = null
+  let isDone = false
+
+  for (let i = 0; i < maxBatches; i++) {
+    const page = (await ctx.runQuery(internal.maintenance.getSkillFingerprintBackfillPageInternal, {
+      cursor: cursor ?? undefined,
+      batchSize,
+    })) as FingerprintBackfillPageResult
+
+    cursor = page.cursor
+    isDone = page.isDone
+
+    for (const item of page.items) {
+      totals.versionsScanned++
+
+      const fingerprint = await hashSkillFiles(item.files)
+
+      const existingFingerprints = new Set(item.existingEntries.map((entry) => entry.fingerprint))
+      const hasAnyEntry = item.existingEntries.length > 0
+      const entryIsCorrect =
+        hasAnyEntry && existingFingerprints.size === 1 && existingFingerprints.has(fingerprint)
+      const versionFingerprintIsCorrect = item.versionFingerprint === fingerprint
+
+      if (hasAnyEntry && !entryIsCorrect) totals.fingerprintMismatches++
+
+      const shouldPatchVersion = !versionFingerprintIsCorrect
+      const shouldReplaceEntries = !entryIsCorrect
+      if (!shouldPatchVersion && !shouldReplaceEntries) continue
+
+      if (shouldPatchVersion) totals.versionsPatched++
+      if (shouldReplaceEntries) totals.fingerprintsInserted++
+
+      if (dryRun) continue
+
+      await ctx.runMutation(internal.maintenance.applySkillFingerprintBackfillPatchInternal, {
+        versionId: item.versionId,
+        fingerprint,
+        patchVersion: shouldPatchVersion,
+        replaceEntries: shouldReplaceEntries,
+        existingEntryIds: shouldReplaceEntries ? item.existingEntries.map((entry) => entry.id) : [],
+      })
+    }
+
+    if (isDone) break
+  }
+
+  if (!isDone) {
+    throw new ConvexError('Backfill incomplete (maxBatches reached)')
+  }
+
+  return { ok: true as const, stats: totals }
+}
+
+export const backfillSkillFingerprintsInternal = internalAction({
+  args: {
+    dryRun: v.optional(v.boolean()),
+    batchSize: v.optional(v.number()),
+    maxBatches: v.optional(v.number()),
+  },
+  handler: backfillSkillFingerprintsInternalHandler,
+})
+
+export const backfillSkillFingerprints: ReturnType<typeof action> = action({
+  args: {
+    dryRun: v.optional(v.boolean()),
+    batchSize: v.optional(v.number()),
+    maxBatches: v.optional(v.number()),
+  },
+  handler: async (ctx, args): Promise<FingerprintBackfillActionResult> => {
+    const { user } = await requireUserFromAction(ctx)
+    assertRole(user, ['admin'])
+    return ctx.runAction(
+      internal.maintenance.backfillSkillFingerprintsInternal,
+      args,
+    ) as Promise<FingerprintBackfillActionResult>
+  },
+})
+
+export const scheduleBackfillSkillFingerprints: ReturnType<typeof action> = action({
+  args: { dryRun: v.optional(v.boolean()) },
+  handler: async (ctx, args) => {
+    const { user } = await requireUserFromAction(ctx)
+    assertRole(user, ['admin'])
+    await ctx.scheduler.runAfter(0, internal.maintenance.backfillSkillFingerprintsInternal, {
+      dryRun: Boolean(args.dryRun),
+      batchSize: DEFAULT_BATCH_SIZE,
+      maxBatches: DEFAULT_MAX_BATCHES,
+    })
+    return { ok: true as const }
+  },
+})
+
+export const getSkillBadgeBackfillPageInternal = internalQuery({
+  args: {
+    cursor: v.optional(v.string()),
+    batchSize: v.optional(v.number()),
+  },
+  handler: async (ctx, args): Promise<BadgeBackfillPageResult> => {
+    const batchSize = clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE)
+    const { page, isDone, continueCursor } = await ctx.db
+      .query('skills')
+      .order('asc')
+      .paginate({ cursor: args.cursor ?? null, numItems: batchSize })
+
+    const items: BadgeBackfillPageItem[] = page.map((skill) => ({
+      skillId: skill._id,
+      ownerUserId: skill.ownerUserId,
+      createdAt: skill.createdAt ?? undefined,
+      updatedAt: skill.updatedAt ?? undefined,
+      batch: skill.batch ?? undefined,
+      badges: skill.badges ?? undefined,
+    }))
+
+    return { items, cursor: continueCursor, isDone }
+  },
+})
+
+export const applySkillBadgeBackfillPatchInternal = internalMutation({
+  args: {
+    skillId: v.id('skills'),
+    badges: v.optional(
+      v.object({
+        redactionApproved: v.optional(
+          v.object({
+            byUserId: v.id('users'),
+            at: v.number(),
+          }),
+        ),
+        highlighted: v.optional(
+          v.object({
+            byUserId: v.id('users'),
+            at: v.number(),
+          }),
+        ),
+        official: v.optional(
+          v.object({
+            byUserId: v.id('users'),
+            at: v.number(),
+          }),
+        ),
+        deprecated: v.optional(
+          v.object({
+            byUserId: v.id('users'),
+            at: v.number(),
+          }),
+        ),
+      }),
+    ),
+  },
+  handler: async (ctx, args) => {
+    await ctx.db.patch(args.skillId, { badges: args.badges ?? undefined, updatedAt: Date.now() })
+    return { ok: true as const }
+  },
+})
+
+export const upsertSkillBadgeRecordInternal = internalMutation({
+  args: {
+    skillId: v.id('skills'),
+    kind: v.union(
+      v.literal('highlighted'),
+      v.literal('official'),
+      v.literal('deprecated'),
+      v.literal('redactionApproved'),
+    ),
+    byUserId: v.id('users'),
+    at: v.number(),
+  },
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query('skillBadges')
+      .withIndex('by_skill_kind', (q) => q.eq('skillId', args.skillId).eq('kind', args.kind))
+      .unique()
+    if (existing) return { inserted: false as const }
+    await ctx.db.insert('skillBadges', {
+      skillId: args.skillId,
+      kind: args.kind,
+      byUserId: args.byUserId,
+      at: args.at,
+    })
+    return { inserted: true as const }
+  },
+})
+
+export type BadgeBackfillActionArgs = {
+  dryRun?: boolean
+  batchSize?: number
+  maxBatches?: number
+}
+
+export type BadgeBackfillActionResult = { ok: true; stats: BadgeBackfillStats }
+
+export async function backfillSkillBadgesInternalHandler(
+  ctx: ActionCtx,
+  args: BadgeBackfillActionArgs,
+): Promise<BadgeBackfillActionResult> {
+  const dryRun = Boolean(args.dryRun)
+  const batchSize = clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE)
+  const maxBatches = clampInt(args.maxBatches ?? DEFAULT_MAX_BATCHES, 1, MAX_MAX_BATCHES)
+
+  const totals: BadgeBackfillStats = {
+    skillsScanned: 0,
+    skillsPatched: 0,
+    highlightsPatched: 0,
+  }
+
+  let cursor: string | null = null
+  let isDone = false
+
+  for (let i = 0; i < maxBatches; i++) {
+    const page = (await ctx.runQuery(internal.maintenance.getSkillBadgeBackfillPageInternal, {
+      cursor: cursor ?? undefined,
+      batchSize,
+    })) as BadgeBackfillPageResult
+
+    cursor = page.cursor
+    isDone = page.isDone
+
+    for (const item of page.items) {
+      totals.skillsScanned++
+
+      const shouldHighlight = item.batch === 'highlighted' && !item.badges?.highlighted
+      if (!shouldHighlight) continue
+
+      totals.skillsPatched++
+      totals.highlightsPatched++
+
+      if (dryRun) continue
+
+      const at = item.updatedAt ?? item.createdAt ?? Date.now()
+      await ctx.runMutation(internal.maintenance.applySkillBadgeBackfillPatchInternal, {
+        skillId: item.skillId,
+        badges: {
+          ...item.badges,
+          highlighted: {
+            byUserId: item.ownerUserId,
+            at,
+          },
+        },
+      })
+    }
+
+    if (isDone) break
+  }
+
+  if (!isDone) {
+    throw new ConvexError('Backfill incomplete (maxBatches reached)')
+  }
+
+  return { ok: true as const, stats: totals }
+}
+
+export const backfillSkillBadgesInternal = internalAction({
+  args: {
+    dryRun: v.optional(v.boolean()),
+    batchSize: v.optional(v.number()),
+    maxBatches: v.optional(v.number()),
+  },
+  handler: backfillSkillBadgesInternalHandler,
+})
+
+export const backfillSkillBadges: ReturnType<typeof action> = action({
+  args: {
+    dryRun: v.optional(v.boolean()),
+    batchSize: v.optional(v.number()),
+    maxBatches: v.optional(v.number()),
+  },
+  handler: async (ctx, args): Promise<BadgeBackfillActionResult> => {
+    const { user } = await requireUserFromAction(ctx)
+    assertRole(user, ['admin'])
+    return ctx.runAction(
+      internal.maintenance.backfillSkillBadgesInternal,
+      args,
+    ) as Promise<BadgeBackfillActionResult>
+  },
+})
+
+export const scheduleBackfillSkillBadges: ReturnType<typeof action> = action({
+  args: { dryRun: v.optional(v.boolean()) },
+  handler: async (ctx, args) => {
+    const { user } = await requireUserFromAction(ctx)
+    assertRole(user, ['admin'])
+    await ctx.scheduler.runAfter(0, internal.maintenance.backfillSkillBadgesInternal, {
+      dryRun: Boolean(args.dryRun),
+      batchSize: DEFAULT_BATCH_SIZE,
+      maxBatches: DEFAULT_MAX_BATCHES,
+    })
+    return { ok: true as const }
+  },
+})
+
+export type SkillBadgeTableBackfillActionResult = {
+  ok: true
+  stats: SkillBadgeTableBackfillStats
+}
+
+export async function backfillSkillBadgeTableInternalHandler(
+  ctx: ActionCtx,
+  args: BadgeBackfillActionArgs,
+): Promise<SkillBadgeTableBackfillActionResult> {
+  const dryRun = Boolean(args.dryRun)
+  const batchSize = clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE)
+  const maxBatches = clampInt(args.maxBatches ?? DEFAULT_MAX_BATCHES, 1, MAX_MAX_BATCHES)
+
+  const totals: SkillBadgeTableBackfillStats = {
+    skillsScanned: 0,
+    recordsInserted: 0,
+  }
+
+  let cursor: string | null = null
+  let isDone = false
+
+  for (let i = 0; i < maxBatches; i++) {
+    const page = (await ctx.runQuery(internal.maintenance.getSkillBadgeBackfillPageInternal, {
+      cursor: cursor ?? undefined,
+      batchSize,
+    })) as BadgeBackfillPageResult
+
+    cursor = page.cursor
+    isDone = page.isDone
+
+    for (const item of page.items) {
+      totals.skillsScanned++
+      const badges = item.badges ?? {}
+      const entries: Array<{ kind: BadgeKind; byUserId: Id<'users'>; at: number }> = []
+
+      if (badges.redactionApproved) {
+        entries.push({
+          kind: 'redactionApproved',
+          byUserId: badges.redactionApproved.byUserId,
+          at: badges.redactionApproved.at,
+        })
+      }
+
+      if (badges.official) {
+        entries.push({
+          kind: 'official',
+          byUserId: badges.official.byUserId,
+          at: badges.official.at,
+        })
+      }
+
+      if (badges.deprecated) {
+        entries.push({
+          kind: 'deprecated',
+          byUserId: badges.deprecated.byUserId,
+          at: badges.deprecated.at,
+        })
+      }
+
+      const highlighted =
+        badges.highlighted ??
+        (item.batch === 'highlighted'
+          ? {
+              byUserId: item.ownerUserId,
+              at: item.updatedAt ?? item.createdAt ?? Date.now(),
+            }
+          : undefined)
+
+      if (highlighted) {
+        entries.push({
+          kind: 'highlighted',
+          byUserId: highlighted.byUserId,
+          at: highlighted.at,
+        })
+      }
+
+      if (dryRun) continue
+
+      for (const entry of entries) {
+        const result = await ctx.runMutation(internal.maintenance.upsertSkillBadgeRecordInternal, {
+          skillId: item.skillId,
+          kind: entry.kind,
+          byUserId: entry.byUserId,
+          at: entry.at,
+        })
+        if (result.inserted) {
+          totals.recordsInserted++
+        }
+      }
+    }
+
+    if (isDone) break
+  }
+
+  if (!isDone) {
+    throw new ConvexError('Backfill incomplete (maxBatches reached)')
+  }
+
+  return { ok: true as const, stats: totals }
+}
+
+export const backfillSkillBadgeTableInternal = internalAction({
+  args: {
+    dryRun: v.optional(v.boolean()),
+    batchSize: v.optional(v.number()),
+    maxBatches: v.optional(v.number()),
+  },
+  handler: backfillSkillBadgeTableInternalHandler,
+})
+
+export const backfillSkillBadgeTable: ReturnType<typeof action> = action({
+  args: {
+    dryRun: v.optional(v.boolean()),
+    batchSize: v.optional(v.number()),
+    maxBatches: v.optional(v.number()),
+  },
+  handler: async (ctx, args): Promise<SkillBadgeTableBackfillActionResult> => {
+    const { user } = await requireUserFromAction(ctx)
+    assertRole(user, ['admin'])
+    return ctx.runAction(
+      internal.maintenance.backfillSkillBadgeTableInternal,
+      args,
+    ) as Promise<SkillBadgeTableBackfillActionResult>
+  },
+})
+
+export const scheduleBackfillSkillBadgeTable: ReturnType<typeof action> = action({
+  args: { dryRun: v.optional(v.boolean()) },
+  handler: async (ctx, args) => {
+    const { user } = await requireUserFromAction(ctx)
+    assertRole(user, ['admin'])
+    await ctx.scheduler.runAfter(0, internal.maintenance.backfillSkillBadgeTableInternal, {
+      dryRun: Boolean(args.dryRun),
+      batchSize: DEFAULT_BATCH_SIZE,
+      maxBatches: DEFAULT_MAX_BATCHES,
+    })
+    return { ok: true as const }
+  },
+})
+
+function clampInt(value: number, min: number, max: number) {
+  const rounded = Math.trunc(value)
+  if (!Number.isFinite(rounded)) return min
+  return Math.min(max, Math.max(min, rounded))
+}