fix(seed): harden SoulHub auto-seed

Author: steipete

CHANGELOG.md

@@ -11,6 +11,7 @@
 ### Fixed
 - Web: stabilize skill OG image generation on server runtimes.
 - Web: prevent skill OG text overflow outside the card.
+- Registry: make SoulHub auto-seed idempotent and non-user-owned.
 
 ## 0.1.0 - 2026-01-07
 

convex/seed.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest'
+import type { Doc } from './_generated/dataModel'
+import { decideSeedStart } from './seed'
+
+function seedState(cursor: string, updatedAt: number) {
+  return { cursor, updatedAt } as unknown as Doc<'githubBackupSyncState'>
+}
+
+describe('decideSeedStart', () => {
+  it('returns done when done', () => {
+    expect(decideSeedStart(seedState('done', Date.now()), Date.now())).toEqual({
+      started: false,
+      reason: 'done',
+    })
+  })
+
+  it('returns running when lock fresh', () => {
+    const now = Date.now()
+    expect(decideSeedStart(seedState('running', now), now + 1000)).toEqual({
+      started: false,
+      reason: 'running',
+    })
+  })
+
+  it('starts when lock stale', () => {
+    const now = Date.now()
+    const stale = now - 10 * 60 * 1000 - 1
+    expect(decideSeedStart(seedState('running', stale), now)).toEqual({
+      started: true,
+      reason: 'patched',
+    })
+  })
+
+  it('starts when missing', () => {
+    expect(decideSeedStart(null, Date.now())).toEqual({ started: true, reason: 'inserted' })
+  })
+})

convex/seed.ts

@@ -1,7 +1,7 @@
 import { v } from 'convex/values'
 import { internal } from './_generated/api'
 import type { Doc, Id } from './_generated/dataModel'
-import type { ActionCtx, DatabaseReader } from './_generated/server'
+import type { ActionCtx, DatabaseReader, DatabaseWriter } from './_generated/server'
 import { action, internalMutation, internalQuery } from './_generated/server'
 import { publishSoulVersionForUser } from './lib/soulPublish'
 import { SOUL_SEED_DISPLAY_NAME, SOUL_SEED_HANDLE, SOUL_SEED_KEY, SOUL_SEEDS } from './seedSouls'
@@ -10,6 +10,11 @@ const SEED_LOCK_STALE_MS = 10 * 60 * 1000
 
 type SeedStateDoc = Doc<'githubBackupSyncState'>
 
+type SeedStartDecision = {
+  started: boolean
+  reason: 'done' | 'running' | 'patched' | 'inserted'
+}
+
 async function getSeedState(ctx: { db: DatabaseReader }): Promise<SeedStateDoc | null> {
   const entries = (await ctx.db
     .query('githubBackupSyncState')
@@ -19,6 +24,28 @@ async function getSeedState(ctx: { db: DatabaseReader }): Promise<SeedStateDoc |
   return entries[0] ?? null
 }
 
+async function cleanupSeedState(ctx: { db: DatabaseWriter }, keepId: Id<'githubBackupSyncState'>) {
+  const entries = (await ctx.db
+    .query('githubBackupSyncState')
+    .withIndex('by_key', (q) => q.eq('key', SOUL_SEED_KEY))
+    .order('desc')
+    .take(50)) as SeedStateDoc[]
+
+  for (const entry of entries) {
+    if (entry._id === keepId) continue
+    await ctx.db.delete(entry._id)
+  }
+}
+
+export function decideSeedStart(existing: SeedStateDoc | null, now: number): SeedStartDecision {
+  const cursor = existing?.cursor ?? null
+  if (cursor === 'done') return { started: false, reason: 'done' }
+  if (cursor === 'running' && existing && now - existing.updatedAt < SEED_LOCK_STALE_MS) {
+    return { started: false, reason: 'running' }
+  }
+  return existing ? { started: true, reason: 'patched' } : { started: true, reason: 'inserted' }
+}
+
 export const getSoulSeedStateInternal = internalQuery({
   args: {},
   handler: async (ctx) => getSeedState(ctx),
@@ -31,13 +58,16 @@ export const setSoulSeedStateInternal = internalMutation({
     const now = Date.now()
     if (existing) {
       await ctx.db.patch(existing._id, { cursor: args.status, updatedAt: now })
+      await cleanupSeedState(ctx, existing._id)
       return existing._id
     }
-    return ctx.db.insert('githubBackupSyncState', {
+    const id = await ctx.db.insert('githubBackupSyncState', {
       key: SOUL_SEED_KEY,
       cursor: args.status,
       updatedAt: now,
     })
+    await cleanupSeedState(ctx, id)
+    return id
   },
 })
 
@@ -46,23 +76,22 @@ export const tryStartSoulSeedInternal = internalMutation({
   handler: async (ctx) => {
     const now = Date.now()
     const existing = await getSeedState(ctx)
-    const cursor = existing?.cursor ?? null
+    const decision = decideSeedStart(existing, now)
 
-    if (cursor === 'done') return { started: false, reason: 'done' as const }
-    if (cursor === 'running' && existing && now - existing.updatedAt < SEED_LOCK_STALE_MS) {
-      return { started: false, reason: 'running' as const }
-    }
+    if (!decision.started) return decision
 
     if (existing) {
       await ctx.db.patch(existing._id, { cursor: 'running', updatedAt: now })
+      await cleanupSeedState(ctx, existing._id)
       return { started: true, reason: 'patched' as const }
     }
 
-    await ctx.db.insert('githubBackupSyncState', {
+    const id = await ctx.db.insert('githubBackupSyncState', {
       key: SOUL_SEED_KEY,
       cursor: 'running',
       updatedAt: now,
     })
+    await cleanupSeedState(ctx, id)
     return { started: true, reason: 'inserted' as const }
   },
 })