@beechcms/api 0.5.0 → 0.6.0-preview.2

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

@@ -0,0 +1,142 @@
+// 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 { D1SchemaMutator } from './schema-mutator.d1'
+
+function makeMockDb() {
+  const runMock = vi.fn().mockResolvedValue({ success: true })
+  const firstMock = vi.fn().mockResolvedValue(null)
+  const allMock = vi.fn().mockResolvedValue({ results: [] })
+  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)
+  const batchMock = vi.fn().mockResolvedValue([])
+
+  return {
+    db: {
+      prepare: prepareMock,
+      batch: batchMock,
+    } as unknown as D1Database,
+    prepareMock,
+    bindMock,
+    runMock,
+    firstMock,
+    allMock,
+    batchMock,
+  }
+}
+
+describe('D1SchemaMutator', () => {
+  describe('getColumns', () => {
+    it('returns null if table has no columns (empty result)', async () => {
+      const { db, allMock } = makeMockDb()
+      allMock.mockResolvedValueOnce({ results: [] })
+      const mutator = new D1SchemaMutator(db)
+      const cols = await mutator.getColumns('users')
+      expect(cols).toBeNull()
+    })
+
+    it('returns set of column names when columns are found', async () => {
+      const { db, allMock, prepareMock } = makeMockDb()
+      allMock.mockResolvedValueOnce({
+        results: [{ name: 'id' }, { name: 'email' }],
+      })
+      const mutator = new D1SchemaMutator(db)
+      const cols = await mutator.getColumns('users')
+      expect(prepareMock).toHaveBeenCalledWith('PRAGMA table_info(users)')
+      expect(cols).toEqual(new Set(['id', 'email']))
+    })
+
+    it('throws error if table name is unsafe', async () => {
+      const { db } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await expect(mutator.getColumns('users; DROP TABLE users;')).rejects.toThrow(
+        'Unsafe table name',
+      )
+    })
+  })
+
+  describe('execDdl', () => {
+    it('returns early if statements are empty', async () => {
+      const { db, batchMock } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await mutator.execDdl([])
+      expect(batchMock).not.toHaveBeenCalled()
+    })
+
+    it('prepares and executes batch DDL statements', async () => {
+      const { db, batchMock, prepareMock } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await mutator.execDdl(['CREATE TABLE test (id TEXT)', 'CREATE INDEX idx ON test (id)'])
+      expect(prepareMock).toHaveBeenCalledTimes(2)
+      expect(batchMock).toHaveBeenCalled()
+    })
+  })
+
+  describe('dropTable', () => {
+    it('executes DROP TABLE IF EXISTS for a safe identifier', async () => {
+      const { db, prepareMock, runMock } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await mutator.dropTable('articles')
+      expect(prepareMock).toHaveBeenCalledWith('DROP TABLE IF EXISTS articles')
+      expect(runMock).toHaveBeenCalled()
+    })
+
+    it('throws error on unsafe table name', async () => {
+      const { db } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await expect(mutator.dropTable('articles; --')).rejects.toThrow('Unsafe identifier')
+    })
+  })
+
+  describe('dropColumn', () => {
+    it('executes ALTER TABLE DROP COLUMN for safe identifiers', async () => {
+      const { db, prepareMock, runMock } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await mutator.dropColumn('articles', 'title')
+      expect(prepareMock).toHaveBeenCalledWith('ALTER TABLE articles DROP COLUMN title')
+      expect(runMock).toHaveBeenCalled()
+    })
+
+    it('throws error on unsafe column name', async () => {
+      const { db } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await expect(mutator.dropColumn('articles', 'title;')).rejects.toThrow('Unsafe identifier')
+    })
+  })
+
+  describe('renameColumn', () => {
+    it('executes ALTER TABLE RENAME COLUMN for safe identifiers', async () => {
+      const { db, prepareMock, runMock } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await mutator.renameColumn('articles', 'old_name', 'new_name')
+      expect(prepareMock).toHaveBeenCalledWith('ALTER TABLE articles RENAME COLUMN old_name TO new_name')
+      expect(runMock).toHaveBeenCalled()
+    })
+
+    it('throws error on unsafe parameters', async () => {
+      const { db } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await expect(mutator.renameColumn('articles', 'old', 'new --')).rejects.toThrow('Unsafe identifier')
+    })
+  })
+
+  describe('execDestructive', () => {
+    it('returns early if statements are empty', async () => {
+      const { db, batchMock } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await mutator.execDestructive([])
+      expect(batchMock).not.toHaveBeenCalled()
+    })
+
+    it('prepares and executes batch destructive statements', async () => {
+      const { db, batchMock, prepareMock } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await mutator.execDestructive(['DROP TABLE test'])
+      expect(prepareMock).toHaveBeenCalledWith('DROP TABLE test')
+      expect(batchMock).toHaveBeenCalled()
+    })
+  })
+})

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)
+    })
+  })
+})