@beechcms/api 0.4.3 → 0.6.0-preview.1

package/src/shared/qstash-notification-service.test.ts

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { QStashNotificationService } from './qstash-notification-service'
+import { Client } from '@upstash/qstash'
+
+// Mock the @upstash/qstash Client
+vi.mock('@upstash/qstash', () => {
+  const publishJSON = vi.fn().mockResolvedValue({ messageId: 'msg_123' })
+  return {
+    Client: vi.fn().mockImplementation(function () {
+      return { publishJSON }
+    }),
+  }
+})
+
+describe('QStashNotificationService', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('delegates publishing to the QStash client with correct URL', async () => {
+    const service = new QStashNotificationService('fake_token', 'https://beechcms.test/')
+    await service.notify({
+      title: 'Hello',
+      message: 'World',
+      type: 'success',
+    })
+
+    const clientInstance = vi.mocked(Client).mock.results[0].value
+    expect(clientInstance.publishJSON).toHaveBeenCalledWith({
+      url: 'https://beechcms.test/api/webhooks/qstash',
+      body: {
+        title: 'Hello',
+        message: 'World',
+        type: 'success',
+      },
+    })
+  })
+
+  it('delegates to the background scheduler when provided', () => {
+    const schedule = vi.fn()
+    const service = new QStashNotificationService('fake_token', 'https://beechcms.test', schedule)
+    
+    service.notify({ title: 'T', message: 'M' })
+    
+    expect(schedule).toHaveBeenCalledTimes(1)
+    expect(schedule.mock.calls[0][0]).toBeInstanceOf(Promise)
+  })
+
+  it('never throws to the caller when the publish write fails', async () => {
+    // Override the mock for this specific test
+    const mockPublish = vi.fn().mockRejectedValue(new Error('network error'))
+    vi.mocked(Client).mockImplementationOnce(function () {
+      return { publishJSON: mockPublish }
+    } as any)
+
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const service = new QStashNotificationService('fake_token', 'https://beechcms.test')
+    
+    await expect(service.notify({ title: 'T', message: 'M' })).resolves.toBeUndefined()
+    expect(consoleSpy).toHaveBeenCalled()
+    consoleSpy.mockRestore()
+  })
+})

package/src/shared/qstash-notification-service.ts

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+import type { INotificationService, CreateNotificationInput } from '@beechcms/core'
+import { Client } from '@upstash/qstash'
+
+type ScheduleBackgroundTask = (task: Promise<unknown>) => void
+
+/**
+ * QStash implementation of {@link INotificationService}.
+ *
+ * This service acts as a publisher, sending the notification payload to Upstash QStash,
+ * which guarantees delivery and retries. QStash will then forward the payload to the
+ * local webhook endpoint where it is actually inserted into D1.
+ */
+export class QStashNotificationService implements INotificationService {
+  private readonly client: Client
+  private readonly webhookUrl: string
+
+  constructor(
+    token: string,
+    appUrl: string,
+    private readonly scheduleBackgroundTask?: ScheduleBackgroundTask,
+    qstashUrl?: string
+  ) {
+    this.client = new Client({ 
+      token,
+      ...(qstashUrl ? { baseUrl: qstashUrl } : {})
+    })
+    this.webhookUrl = `${appUrl.replace(/\/$/, '')}/api/webhooks/qstash`
+  }
+
+  notify(input: CreateNotificationInput): Promise<void> | void {
+    const publishPromise = this.runPublish(input)
+
+    if (this.scheduleBackgroundTask) {
+      this.scheduleBackgroundTask(publishPromise)
+      return
+    }
+
+    return publishPromise
+  }
+
+  private async runPublish(input: CreateNotificationInput): Promise<void> {
+    try {
+      await this.client.publishJSON({
+        url: this.webhookUrl,
+        body: input,
+      })
+    } catch (error) {
+      console.error('QStashNotificationService: failed to publish notification', error)
+    }
+  }
+}

package/src/shared/query-utils.ts

@@ -1,3 +1,7 @@
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
 import type { FilterGroup, FilterType } from '@beechcms/core'
 
 /** Entry parsata per le risposte API — contratto immutabile (C7). */

package/src/shared/request-utils.ts

@@ -1,3 +1,7 @@
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
 import type { HonoRequest } from "hono"
 
 /** The header Cloudflare sets on every incoming request to the Worker. */

package/src/shared/schema-mutator.d1.ts

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+/// <reference types="@cloudflare/workers-types" />
+import type { ISchemaMutator } from '@beechcms/core'
+
+export class D1SchemaMutator implements ISchemaMutator {
+  constructor(private readonly db: D1Database) {}
+
+  async getColumns(table: string): Promise<Set<string> | null> {
+    // PRAGMA table_info returns rows {cid,name,type,notnull,dflt_value,pk}.
+    // Table name cannot be parameterized in PRAGMA — validate it is a safe identifier.
+    if (!/^[A-Za-z0-9_]+$/.test(table)) throw new Error(`Unsafe table name: ${table}`)
+    const rs = await this.db.prepare(`PRAGMA table_info(${table})`).all<{ name: string }>()
+    const rows = rs.results ?? []
+    if (rows.length === 0) return null // table absent
+    return new Set(rows.map(r => r.name))
+  }
+
+  async execDdl(statements: string[]): Promise<void> {
+    if (statements.length === 0) return
+    // D1 batch is atomic per call; if one statement fails, the rest roll back.
+    await this.db.batch(statements.map(s => this.db.prepare(s)))
+  }
+
+  // --- destructive (sprint 06 — Danger Zone) -------------------------------
+  // These emit IRREVERSIBLE SQL. Identifiers cannot be parameterized in DDL, so
+  // every table/column name is validated against the same `^[A-Za-z0-9_]+$`
+  // guard getColumns already applies before interpolation.
+
+  private static assertIdentifier(name: string): void {
+    if (!/^[A-Za-z0-9_]+$/.test(name)) throw new Error(`Unsafe identifier: ${name}`)
+  }
+
+  async dropTable(table: string): Promise<void> {
+    D1SchemaMutator.assertIdentifier(table)
+    await this.db.prepare(`DROP TABLE IF EXISTS ${table}`).run()
+  }
+
+  async dropColumn(table: string, column: string): Promise<void> {
+    D1SchemaMutator.assertIdentifier(table)
+    D1SchemaMutator.assertIdentifier(column)
+    await this.db.prepare(`ALTER TABLE ${table} DROP COLUMN ${column}`).run()
+  }
+
+  async renameColumn(table: string, from: string, to: string): Promise<void> {
+    D1SchemaMutator.assertIdentifier(table)
+    D1SchemaMutator.assertIdentifier(from)
+    D1SchemaMutator.assertIdentifier(to)
+    await this.db.prepare(`ALTER TABLE ${table} RENAME COLUMN ${from} TO ${to}`).run()
+  }
+
+  async execDestructive(statements: string[]): Promise<void> {
+    if (statements.length === 0) return
+    // The statements come from the core destructive generators
+    // (generateDropTable / generateRetypeColumn / planFtsRebuild), which only
+    // interpolate slugs/aliases already validated by the seed registry
+    // (`^[a-z0-9_]+$`). FTS trigger bodies legitimately contain internal
+    // semicolons (BEGIN … ; END), so we do not split or reject on `;`.
+    // D1 batch is atomic per call; if one statement fails, the rest roll back.
+    await this.db.batch(statements.map(s => this.db.prepare(s)))
+  }
+}

package/src/shared/seed-layout.repository.d1.test.ts

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { D1SeedLayoutRepository } from './seed-layout.repository.d1'
+import type { FormLayout } from '@beechcms/core'
+
+function makeMockDb(opts: { firstResult?: unknown; allResults?: unknown[] } = {}) {
+  const { firstResult = null, allResults = [] } = opts
+  const runMock = vi.fn().mockResolvedValue({ success: true })
+  const firstMock = vi.fn().mockResolvedValue(firstResult)
+  const allMock = vi.fn().mockResolvedValue({ results: allResults })
+  const bindMock = vi.fn(() => ({ run: runMock, first: firstMock, all: allMock }))
+  const stmt = { bind: bindMock, run: runMock, first: firstMock, all: allMock }
+  const prepareMock = vi.fn(() => stmt)
+  return { db: { prepare: prepareMock } as any, prepareMock, bindMock, runMock, firstMock, allMock }
+}
+
+describe('D1SeedLayoutRepository', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  describe('get', () => {
+    it('returns null when the layout is not found', async () => {
+      const { db } = makeMockDb({ firstResult: null })
+      const repo = new D1SeedLayoutRepository(db)
+      const res = await repo.get('non-existent')
+      expect(res).toBeNull()
+    })
+
+    it('returns mapped record when layout is found and layout JSON is parsed', async () => {
+      const mockLayout: FormLayout = { tabs: [] }
+      const row = {
+        slug: 'pages',
+        layout: JSON.stringify(mockLayout),
+        updated_at: 123456,
+        updated_by: 'admin-user',
+      }
+      const { db, prepareMock, bindMock } = makeMockDb({ firstResult: row })
+      const repo = new D1SeedLayoutRepository(db)
+
+      const res = await repo.get('pages')
+      expect(prepareMock).toHaveBeenCalledWith(expect.stringContaining('SELECT slug, layout, updated_at, updated_by FROM seed_layouts'))
+      expect(bindMock).toHaveBeenCalledWith('pages')
+      expect(res).toEqual({
+        slug: 'pages',
+        layout: mockLayout,
+        updatedAt: 123456,
+        updatedBy: 'admin-user',
+      })
+    })
+  })
+
+  describe('getAllAsMap', () => {
+    it('returns an empty map when there are no records', async () => {
+      const { db } = makeMockDb({ allResults: [] })
+      const repo = new D1SeedLayoutRepository(db)
+      const map = await repo.getAllAsMap()
+      expect(map).toBeInstanceOf(Map)
+      expect(map.size).toBe(0)
+    })
+
+    it('returns a populated map and skips corrupt JSON rows', async () => {
+      const allResults = [
+        { slug: 'pages', layout: JSON.stringify({ tabs: [{ id: 't1', label: 'T1', sections: [] }] }) },
+        { slug: 'corrupted', layout: '{invalid-json' },
+        { slug: 'posts', layout: JSON.stringify({ tabs: [{ id: 't2', label: 'T2', sections: [] }] }) },
+      ]
+      const { db, prepareMock } = makeMockDb({ allResults })
+      const repo = new D1SeedLayoutRepository(db)
+
+      const map = await repo.getAllAsMap()
+      expect(prepareMock).toHaveBeenCalledWith(expect.stringContaining('SELECT slug, layout FROM seed_layouts'))
+      expect(map.size).toBe(2)
+      expect(map.get('pages')).toEqual({ tabs: [{ id: 't1', label: 'T1', sections: [] }] })
+      expect(map.get('posts')).toEqual({ tabs: [{ id: 't2', label: 'T2', sections: [] }] })
+      expect(map.has('corrupted')).toBe(false)
+    })
+  })
+
+  describe('upsert', () => {
+    it('prepares and binds the correct layout layout JSON and timestamp', async () => {
+      const mockDate = new Date('2026-06-04T12:00:00Z')
+      vi.setSystemTime(mockDate)
+      const expectedTimestamp = Math.floor(mockDate.getTime() / 1000)
+
+      const { db, prepareMock, bindMock } = makeMockDb()
+      const repo = new D1SeedLayoutRepository(db)
+
+      const layout: FormLayout = { tabs: [{ id: 'tab-1', label: 'Tab 1', sections: [] }] }
+      await repo.upsert('articles', layout, 'editor-1')
+
+      expect(prepareMock).toHaveBeenCalledWith(expect.stringContaining('INSERT INTO seed_layouts'))
+      expect(bindMock).toHaveBeenCalledWith('articles', JSON.stringify(layout), expectedTimestamp, 'editor-1')
+    })
+  })
+
+  describe('remove', () => {
+    it('deletes the layout by slug', async () => {
+      const { db, prepareMock, bindMock } = makeMockDb()
+      const repo = new D1SeedLayoutRepository(db)
+
+      await repo.remove('products')
+      expect(prepareMock).toHaveBeenCalledWith(expect.stringContaining('DELETE FROM seed_layouts WHERE slug = ?'))
+      expect(bindMock).toHaveBeenCalledWith('products')
+    })
+  })
+})

package/src/shared/seed-layout.repository.d1.ts

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+/// <reference types="@cloudflare/workers-types" />
+import type { ISeedLayoutRepository, SeedLayoutRecord, FormLayout } from '@beechcms/core'
+
+export class D1SeedLayoutRepository implements ISeedLayoutRepository {
+  constructor(private readonly db: D1Database) {}
+
+  async get(slug: string): Promise<SeedLayoutRecord | null> {
+    const row = await this.db
+      .prepare('SELECT slug, layout, updated_at, updated_by FROM seed_layouts WHERE slug = ? LIMIT 1')
+      .bind(slug)
+      .first<{ slug: string; layout: string; updated_at: number; updated_by: string }>()
+    if (!row) return null
+    return {
+      slug: row.slug,
+      layout: JSON.parse(row.layout) as FormLayout,
+      updatedAt: row.updated_at,
+      updatedBy: row.updated_by,
+    }
+  }
+
+  async getAllAsMap(): Promise<Map<string, FormLayout>> {
+    const rs = await this.db
+      .prepare('SELECT slug, layout FROM seed_layouts')
+      .all<{ slug: string; layout: string }>()
+    const map = new Map<string, FormLayout>()
+    for (const r of (rs.results ?? [])) {
+      try {
+        map.set(r.slug, JSON.parse(r.layout) as FormLayout)
+      } catch {
+        // skip corrupt row
+      }
+    }
+    return map
+  }
+
+  async upsert(slug: string, layout: FormLayout, updatedBy: string): Promise<void> {
+    const json = JSON.stringify(layout)
+    const now = Math.floor(Date.now() / 1000)
+    await this.db
+      .prepare(`
+        INSERT INTO seed_layouts (slug, layout, updated_at, updated_by)
+        VALUES (?, ?, ?, ?)
+        ON CONFLICT(slug) DO UPDATE SET
+          layout     = excluded.layout,
+          updated_at = excluded.updated_at,
+          updated_by = excluded.updated_by
+      `)
+      .bind(slug, json, now, updatedBy)
+      .run()
+  }
+
+  async remove(slug: string): Promise<void> {
+    await this.db
+      .prepare('DELETE FROM seed_layouts WHERE slug = ?')
+      .bind(slug)
+      .run()
+  }
+}

package/src/shared/seed-registry-cache.test.ts

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { getHydratedRegistry, __resetSeedRegistryCache } from './seed-registry-cache'
+import type { ISeedRepository, SeedRecord, Seed } from '@beechcms/core'
+
+const mockSeed: Seed = {
+  slug: 'posts',
+  label: 'Posts',
+  displayNameAlias: 'title',
+  branches: [{ id: 'br_01', alias: 'title', label: 'Title', type: 'text' }],
+}
+
+function makeRepo(version: number, seeds: Seed[] = [mockSeed]): ISeedRepository & { listActive: ReturnType<typeof vi.fn> } {
+  return {
+    listActive: vi.fn().mockResolvedValue(seeds),
+    listAll: vi.fn().mockResolvedValue([]),
+    get: vi.fn().mockResolvedValue(null),
+    upsert: vi.fn().mockResolvedValue(undefined),
+    softDelete: vi.fn().mockResolvedValue(undefined),
+    getRegistryVersion: vi.fn().mockResolvedValue(version),
+    bumpRegistryVersion: vi.fn().mockResolvedValue(version + 1),
+  }
+}
+
+describe('getHydratedRegistry', () => {
+  beforeEach(() => __resetSeedRegistryCache())
+
+  it('builds registry on first call and calls listActive once', async () => {
+    const repo = makeRepo(1)
+    const { registry } = await getHydratedRegistry(repo)
+    expect(repo.listActive).toHaveBeenCalledTimes(1)
+    expect(registry.get('posts')).not.toBeNull()
+  })
+
+  it('reuses cached registry when version and TTL match', async () => {
+    const repo = makeRepo(1)
+    await getHydratedRegistry(repo)
+    await getHydratedRegistry(repo)
+    expect(repo.listActive).toHaveBeenCalledTimes(1)
+  })
+
+  it('rebuilds when version token changes', async () => {
+    const repo1 = makeRepo(1)
+    await getHydratedRegistry(repo1)
+    expect(repo1.listActive).toHaveBeenCalledTimes(1)
+
+    const repo2 = makeRepo(2)
+    await getHydratedRegistry(repo2)
+    expect(repo2.listActive).toHaveBeenCalledTimes(1)
+  })
+
+  it('empty listActive produces empty registry without throwing', async () => {
+    const repo = makeRepo(1, [])
+    const { registry } = await getHydratedRegistry(repo)
+    expect(registry.all()).toHaveLength(0)
+    expect(registry.get('posts')).toBeNull()
+  })
+
+  it('backrefMap is returned alongside registry', async () => {
+    const repo = makeRepo(1)
+    const { backrefMap } = await getHydratedRegistry(repo)
+    expect(backrefMap).toBeDefined()
+    expect(typeof backrefMap).toBe('object')
+  })
+})

package/src/shared/seed-registry-cache.ts

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+import { SeedRegistry, buildBackrefMap } from '@beechcms/core'
+import type { ISeedRegistry, BackrefMap, Seed, ISeedRepository } from '@beechcms/core'
+
+interface CachedRegistry {
+  version: number
+  builtAt: number
+  registry: ISeedRegistry
+  backrefMap: BackrefMap
+}
+
+// Module-level = isolate-level. Survives across requests on the same isolate,
+// re-initialised on cold start.
+let cache: CachedRegistry | null = null
+
+// Even if the token read fails, never serve a build older than this.
+const TTL_MS = 5_000
+
+/**
+ * Returns a fresh-enough { registry, backrefMap }. Reads the version token once per
+ * request (cheap indexed D1 read); rebuilds from listActive() only when the token
+ * changed or TTL lapsed.
+ */
+export async function getHydratedRegistry(
+  repo: ISeedRepository,
+): Promise<{ registry: ISeedRegistry; backrefMap: BackrefMap }> {
+  const version = await repo.getRegistryVersion()
+  const now = Date.now()
+  if (cache && cache.version === version && now - cache.builtAt < TTL_MS) {
+    return { registry: cache.registry, backrefMap: cache.backrefMap }
+  }
+  const seeds = await repo.listActive()
+  return rebuild(seeds, version, now)
+}
+
+function rebuild(seeds: Seed[], version: number, now: number) {
+  const registry = new SeedRegistry(seeds)
+  const backrefMap = buildBackrefMap(seeds)
+  cache = { version, builtAt: now, registry, backrefMap }
+  return { registry, backrefMap }
+}
+
+/** Test seam: drop the isolate cache. */
+export function __resetSeedRegistryCache(): void {
+  cache = null
+}

package/src/shared/seed.repository.d1.test.ts

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+import { describe, it, expect, vi } from 'vitest'
+import { D1SeedRepository } from './seed.repository.d1'
+import type { Seed } from '@beechcms/core'
+
+const mockSeed: Seed = {
+  slug: 'posts',
+  label: 'Posts',
+  displayNameAlias: 'title',
+  branches: [{ id: 'br_01', alias: 'title', label: 'Title', type: 'text' }],
+}
+
+function makeMockDb(opts: {
+  firstResult?: unknown
+  allResults?: unknown[]
+  runOk?: boolean
+} = {}) {
+  const { firstResult = null, allResults = [], runOk = true } = opts
+  const runMock = vi.fn().mockResolvedValue({ success: runOk })
+  const firstMock = vi.fn().mockResolvedValue(firstResult)
+  const allMock = vi.fn().mockResolvedValue({ results: allResults })
+  const bindMock = vi.fn(() => ({ run: runMock, first: firstMock, all: allMock }))
+  const stmt = { bind: bindMock, run: runMock, first: firstMock, all: allMock }
+  const prepareMock = vi.fn(() => stmt)
+  return { db: { prepare: prepareMock } as unknown as D1Database, prepareMock, bindMock, runMock, firstMock, allMock }
+}
+
+describe('D1SeedRepository', () => {
+  describe('listActive', () => {
+    it('queries active seeds ordered by created_at ASC', async () => {
+      const row = { definition: JSON.stringify(mockSeed) }
+      const { db, prepareMock } = makeMockDb({ allResults: [row] })
+      const repo = new D1SeedRepository(db)
+      const result = await repo.listActive()
+      expect(prepareMock).toHaveBeenCalledWith(expect.stringContaining("status = 'active'"))
+      expect(result).toHaveLength(1)
+      expect(result[0].slug).toBe('posts')
+    })
+
+    it('skips corrupt JSON rows without throwing', async () => {
+      const { db } = makeMockDb({ allResults: [{ definition: 'not-json' }] })
+      const result = await new D1SeedRepository(db).listActive()
+      expect(result).toHaveLength(0)
+    })
+  })
+
+  describe('listAll', () => {
+    it('returns all rows including deleted', async () => {
+      const row = {
+        slug: 'posts',
+        definition: JSON.stringify(mockSeed),
+        status: 'deleted',
+        source: 'code',
+        created_at: 1000,
+        updated_at: 2000,
+      }
+      const { db } = makeMockDb({ allResults: [row] })
+      const result = await new D1SeedRepository(db).listAll()
+      expect(result).toHaveLength(1)
+      expect(result[0].status).toBe('deleted')
+      expect(result[0].source).toBe('code')
+    })
+  })
+
+  describe('get', () => {
+    it('returns a SeedRecord when found', async () => {
+      const row = {
+        slug: 'posts',
+        definition: JSON.stringify(mockSeed),
+        status: 'active',
+        source: 'runtime',
+        created_at: 1000,
+        updated_at: 1000,
+      }
+      const { db, bindMock } = makeMockDb({ firstResult: row })
+      const result = await new D1SeedRepository(db).get('posts')
+      expect(result).not.toBeNull()
+      expect(result!.slug).toBe('posts')
+      expect(bindMock).toHaveBeenCalledWith('posts')
+    })
+
+    it('returns null when not found', async () => {
+      const { db } = makeMockDb({ firstResult: null })
+      expect(await new D1SeedRepository(db).get('ghost')).toBeNull()
+    })
+  })
+
+  describe('upsert', () => {
+    it('prepares INSERT … ON CONFLICT statement with correct bindings', async () => {
+      const { db, prepareMock, bindMock } = makeMockDb()
+      await new D1SeedRepository(db).upsert('posts', mockSeed)
+      expect(prepareMock).toHaveBeenCalledWith(expect.stringContaining('ON CONFLICT'))
+      const [slug, definition, source] = bindMock.mock.calls[0]
+      expect(slug).toBe('posts')
+      expect(JSON.parse(definition as string).slug).toBe('posts')
+      expect(source).toBe('runtime')
+    })
+
+    it('passes source=code when specified', async () => {
+      const { db, bindMock } = makeMockDb()
+      await new D1SeedRepository(db).upsert('posts', mockSeed, 'code')
+      expect(bindMock.mock.calls[0][2]).toBe('code')
+    })
+  })
+
+  describe('softDelete', () => {
+    it('issues UPDATE SET status=deleted', async () => {
+      const { db, prepareMock, bindMock } = makeMockDb()
+      await new D1SeedRepository(db).softDelete('posts')
+      expect(prepareMock).toHaveBeenCalledWith(expect.stringContaining("status = 'deleted'"))
+      expect(bindMock.mock.calls[0]).toContain('posts')
+    })
+  })
+
+  describe('getRegistryVersion', () => {
+    it('returns parsed integer from seed_meta', async () => {
+      const { db } = makeMockDb({ firstResult: { value: '7' } })
+      expect(await new D1SeedRepository(db).getRegistryVersion()).toBe(7)
+    })
+
+    it('returns 1 when row not found', async () => {
+      const { db } = makeMockDb({ firstResult: null })
+      expect(await new D1SeedRepository(db).getRegistryVersion()).toBe(1)
+    })
+  })
+
+  describe('bumpRegistryVersion', () => {
+    it('issues UPDATE … RETURNING and returns new version', async () => {
+      const { db, prepareMock } = makeMockDb({ firstResult: { value: '5' } })
+      const result = await new D1SeedRepository(db).bumpRegistryVersion()
+      expect(prepareMock).toHaveBeenCalledWith(expect.stringContaining('RETURNING'))
+      expect(result).toBe(5)
+    })
+
+    it('returns 1 as fallback when RETURNING yields nothing', async () => {
+      const { db } = makeMockDb({ firstResult: null })
+      expect(await new D1SeedRepository(db).bumpRegistryVersion()).toBe(1)
+    })
+  })
+})