bunderstack 0.15.0 → 0.15.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunderstack",
-  "version": "0.15.0",
+  "version": "0.15.2",
   "description": "Batteries-included backend framework for Bun: CRUD APIs, auth, file storage, realtime, tRPC, email, and validated env from a single Drizzle schema and config object.",
   "keywords": [
     "backend",

package/src/blueprint-generator.ts

@@ -1,4 +1,11 @@
-import { mkdir, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises'
+import {
+  mkdir,
+  readFile,
+  realpath,
+  rename,
+  rm,
+  writeFile,
+} from 'node:fs/promises'
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 
@@ -25,7 +32,9 @@ export type GenerateBlueprintResult = {
 
 export class BlueprintCheckError extends Error {
   constructor() {
-    super('bunderstack.blueprint.yaml is missing or stale; run `bunderstack blueprint`')
+    super(
+      'bunderstack.blueprint.yaml is missing or stale; run `bunderstack blueprint`',
+    )
     this.name = 'BlueprintCheckError'
   }
 }
@@ -44,7 +53,9 @@ function requireRelativePath(value: string, label: string): string {
     isAbsolute(normalized) ||
     normalized.split('/').some((part) => !part || part === '..')
   ) {
-    throw new Error(`[bunderstack] ${label} must be a relative path without traversal`)
+    throw new Error(
+      `[bunderstack] ${label} must be a relative path without traversal`,
+    )
   }
   return normalized
 }
@@ -52,27 +63,46 @@ function requireRelativePath(value: string, label: string): string {
 function resolveWithin(root: string, value: string, label: string): string {
   const path = resolve(root, requireRelativePath(value, label))
   const pathFromRoot = relative(root, path)
-  if (pathFromRoot === '..' || pathFromRoot.startsWith('../') || isAbsolute(pathFromRoot)) {
-    throw new Error(`[bunderstack] ${label} must stay within the application directory`)
+  if (
+    pathFromRoot === '..' ||
+    pathFromRoot.startsWith('../') ||
+    isAbsolute(pathFromRoot)
+  ) {
+    throw new Error(
+      `[bunderstack] ${label} must stay within the application directory`,
+    )
   }
   return path
 }
 
-function normalizeProjectPath(root: string, value: string, label: string): string {
+function normalizeProjectPath(
+  root: string,
+  value: string,
+  label: string,
+): string {
   if (!isAbsolute(value)) return requireRelativePath(value, label)
   const pathFromRoot = relative(root, resolve(value)) || '.'
   return requireRelativePath(pathFromRoot, label)
 }
 
-function requireScript(pkg: AppPackage, name: 'build' | 'start' | 'worker', required: boolean): boolean {
+function requireScript(
+  pkg: AppPackage,
+  name: 'build' | 'start' | 'worker',
+  required: boolean,
+): boolean {
   const value = pkg.scripts?.[name]
   if (typeof value === 'string' && value.trim()) return true
-  if (required) throw new Error(`[bunderstack] package.json requires a non-empty "${name}" script`)
+  if (required)
+    throw new Error(
+      `[bunderstack] package.json requires a non-empty "${name}" script`,
+    )
   return false
 }
 
 async function packageVersion(): Promise<string> {
-  const pkg = (await Bun.file(new URL('../package.json', import.meta.url)).json()) as { version: string }
+  const pkg = (await Bun.file(
+    new URL('../package.json', import.meta.url),
+  ).json()) as { version: string }
   return pkg.version
 }
 
@@ -84,28 +114,38 @@ export async function generateBlueprint(
   const pkg = JSON.parse(await readFile(packagePath, 'utf8')) as AppPackage
   const allDependencies = { ...pkg.dependencies, ...pkg.devDependencies }
   if (typeof allDependencies['@tanstack/react-start'] !== 'string') {
-    throw new Error('[bunderstack] package.json must depend on @tanstack/react-start')
+    throw new Error(
+      '[bunderstack] package.json must depend on @tanstack/react-start',
+    )
   }
   requireScript(pkg, 'build', true)
   requireScript(pkg, 'start', true)
 
   const configuredEntry = pkg.bunderstack?.entry
   const entry = requireRelativePath(
-    options.entry ?? (typeof configuredEntry === 'string' ? configuredEntry : 'src/bunderstack.ts'),
+    options.entry ??
+      (typeof configuredEntry === 'string'
+        ? configuredEntry
+        : 'src/bunderstack.ts'),
     'entry',
   )
   const entryPath = resolveWithin(directory, entry, 'entry')
   if (!(await Bun.file(entryPath).exists())) {
     throw new Error(`[bunderstack] entry does not exist: ${entry}`)
   }
-  const output = requireRelativePath(options.output ?? 'bunderstack.blueprint.yaml', 'output')
+  const output = requireRelativePath(
+    options.output ?? 'bunderstack.blueprint.yaml',
+    'output',
+  )
   const outputPath = resolveWithin(directory, output, 'output')
 
   const previousIntrospection = process.env.BUNDERSTACK_INTROSPECT
   process.env.BUNDERSTACK_INTROSPECT = '1'
   let app: { manifest?: unknown; close?: () => Promise<void> } | undefined
   try {
-    const module = (await import(`${pathToFileURL(entryPath).href}?blueprint=${Date.now()}`)) as {
+    const module = (await import(
+      `${pathToFileURL(entryPath).href}?blueprint=${Date.now()}`
+    )) as {
       app?: typeof app
     }
     app = module.app
@@ -123,7 +163,9 @@ export async function generateBlueprint(
       'meta',
       '_journal.json',
     )
-    const migrationMode = (await Bun.file(migrationJournal).exists()) ? 'migrations' : 'push'
+    const migrationMode = (await Bun.file(migrationJournal).exists())
+      ? 'migrations'
+      : 'push'
     const blueprint = blueprintFromManifest({
       manifest: {
         ...manifest,
@@ -134,12 +176,15 @@ export async function generateBlueprint(
       migrationMode,
     })
     const source = serializeBlueprint(blueprint)
-    const existing = (await Bun.file(outputPath).exists()) ? await Bun.file(outputPath).text() : undefined
+    const existing = (await Bun.file(outputPath).exists())
+      ? await Bun.file(outputPath).text()
+      : undefined
     if (options.check) {
       if (existing !== source) throw new BlueprintCheckError()
       return { path: outputPath, blueprint, source, changed: false }
     }
-    if (existing === source) return { path: outputPath, blueprint, source, changed: false }
+    if (existing === source)
+      return { path: outputPath, blueprint, source, changed: false }
     await mkdir(dirname(outputPath), { recursive: true })
     const temporary = `${outputPath}.${process.pid}.${Date.now()}.tmp`
     try {
@@ -151,7 +196,8 @@ export async function generateBlueprint(
     return { path: outputPath, blueprint, source, changed: true }
   } finally {
     await app?.close?.()
-    if (previousIntrospection === undefined) delete process.env.BUNDERSTACK_INTROSPECT
+    if (previousIntrospection === undefined)
+      delete process.env.BUNDERSTACK_INTROSPECT
     else process.env.BUNDERSTACK_INTROSPECT = previousIntrospection
   }
 }

package/src/blueprint.ts

@@ -1,9 +1,10 @@
 import { parse, stringify } from 'yaml'
 import { z } from 'zod'
 
-import { parseCron } from './jobs/cron'
 import type { BunderstackManifest } from './manifest'
 
+import { parseCron } from './jobs/cron'
+
 export type MigrationMode = 'migrations' | 'push'
 
 export type BunderstackBlueprint = {
@@ -48,12 +49,18 @@ const cronSchedule = nonEmpty.refine(
 const blueprintSchema = z
   .object({
     version: z.literal(1),
-    generator: z.object({ name: z.literal('bunderstack'), version: nonEmpty }).strict(),
+    generator: z
+      .object({ name: z.literal('bunderstack'), version: nonEmpty })
+      .strict(),
     application: z
       .object({
         framework: z.literal('tanstack-start'),
         scripts: z
-          .object({ build: z.literal('build'), start: z.literal('start'), worker: z.literal('worker').optional() })
+          .object({
+            build: z.literal('build'),
+            start: z.literal('start'),
+            worker: z.literal('worker').optional(),
+          })
           .strict(),
       })
       .strict(),
@@ -68,29 +75,65 @@ const blueprintSchema = z
             migrationsDirectory: relativePath,
             migrationMode: z.enum(['migrations', 'push']),
             tables: z.array(
-              z.object({ exportName: nonEmpty, physicalName: nonEmpty, system: z.boolean() }).strict(),
+              z
+                .object({
+                  exportName: nonEmpty,
+                  physicalName: nonEmpty,
+                  system: z.boolean(),
+                })
+                .strict(),
             ),
           })
           .strict(),
         storage: z
           .object({
             defaultBucket: nonEmpty,
-            buckets: z.array(z.object({ name: nonEmpty, visibility: z.enum(['public', 'private']) }).strict()),
+            buckets: z.array(
+              z
+                .object({
+                  name: nonEmpty,
+                  visibility: z.enum(['public', 'private']),
+                })
+                .strict(),
+            ),
           })
           .strict(),
-        realtime: z.object({ required: z.literal(true) }).strict().optional(),
+        realtime: z
+          .object({ required: z.literal(true) })
+          .strict()
+          .optional(),
       })
       .strict(),
     environment: z.array(
-      z.object({ key: nonEmpty, required: z.boolean(), scope: z.enum(['server', 'client']) }).strict(),
+      z
+        .object({
+          key: nonEmpty,
+          required: z.boolean(),
+          scope: z.enum(['server', 'client']),
+        })
+        .strict(),
     ),
     background: z
       .object({
         worker: z.object({ required: z.boolean() }).strict(),
         jobs: z.array(z.object({ name: nonEmpty }).strict()),
-        cron: z.array(z.object({ name: nonEmpty, schedule: cronSchedule, timezone: z.literal('UTC') }).strict()),
+        cron: z.array(
+          z
+            .object({
+              name: nonEmpty,
+              schedule: cronSchedule,
+              timezone: z.literal('UTC'),
+            })
+            .strict(),
+        ),
         maintenance: z.array(
-          z.object({ name: z.literal('storage-sweep'), schedule: cronSchedule, timezone: z.literal('UTC') }).strict(),
+          z
+            .object({
+              name: z.literal('storage-sweep'),
+              schedule: cronSchedule,
+              timezone: z.literal('UTC'),
+            })
+            .strict(),
         ),
       })
       .strict(),
@@ -104,29 +147,61 @@ function sortBy<T>(entries: readonly T[], key: (entry: T) => string): T[] {
 function rejectDuplicates(collection: string, values: readonly string[]): void {
   const seen = new Set<string>()
   for (const value of values) {
-    if (seen.has(value)) throw new Error(`[bunderstack] duplicate ${collection} "${value}"`)
+    if (seen.has(value))
+      throw new Error(`[bunderstack] duplicate ${collection} "${value}"`)
     seen.add(value)
   }
 }
 
 export function parseBlueprint(value: unknown): BunderstackBlueprint {
   const blueprint = blueprintSchema.parse(value) as BunderstackBlueprint
-  rejectDuplicates('database physical table', blueprint.resources.database.tables.map((entry) => entry.physicalName))
-  rejectDuplicates('database export table', blueprint.resources.database.tables.map((entry) => entry.exportName))
-  rejectDuplicates('storage bucket', blueprint.resources.storage.buckets.map((entry) => entry.name))
-  rejectDuplicates('environment key', blueprint.environment.map((entry) => entry.key))
-  rejectDuplicates('background job', blueprint.background.jobs.map((entry) => entry.name))
-  rejectDuplicates('background cron', blueprint.background.cron.map((entry) => entry.name))
-  rejectDuplicates('background maintenance', blueprint.background.maintenance.map((entry) => entry.name))
-  if (!blueprint.resources.storage.buckets.some((bucket) => bucket.name === blueprint.resources.storage.defaultBucket)) {
-    throw new Error('[bunderstack] storage defaultBucket must be declared in storage buckets')
+  rejectDuplicates(
+    'database physical table',
+    blueprint.resources.database.tables.map((entry) => entry.physicalName),
+  )
+  rejectDuplicates(
+    'database export table',
+    blueprint.resources.database.tables.map((entry) => entry.exportName),
+  )
+  rejectDuplicates(
+    'storage bucket',
+    blueprint.resources.storage.buckets.map((entry) => entry.name),
+  )
+  rejectDuplicates(
+    'environment key',
+    blueprint.environment.map((entry) => entry.key),
+  )
+  rejectDuplicates(
+    'background job',
+    blueprint.background.jobs.map((entry) => entry.name),
+  )
+  rejectDuplicates(
+    'background cron',
+    blueprint.background.cron.map((entry) => entry.name),
+  )
+  rejectDuplicates(
+    'background maintenance',
+    blueprint.background.maintenance.map((entry) => entry.name),
+  )
+  if (
+    !blueprint.resources.storage.buckets.some(
+      (bucket) => bucket.name === blueprint.resources.storage.defaultBucket,
+    )
+  ) {
+    throw new Error(
+      '[bunderstack] storage defaultBucket must be declared in storage buckets',
+    )
   }
   const workerRequired = blueprint.background.jobs.length > 0
   if (blueprint.background.worker.required !== workerRequired) {
-    throw new Error('[bunderstack] background worker.required must match declared queue jobs')
+    throw new Error(
+      '[bunderstack] background worker.required must match declared queue jobs',
+    )
   }
   if (Boolean(blueprint.application.scripts.worker) !== workerRequired) {
-    throw new Error('[bunderstack] application worker script must match declared queue jobs')
+    throw new Error(
+      '[bunderstack] application worker script must match declared queue jobs',
+    )
   }
   return blueprint
 }
@@ -143,27 +218,39 @@ export function blueprintFromManifest(args: {
     generator: { name: 'bunderstack', version: args.generatorVersion },
     application: {
       framework: 'tanstack-start',
-      scripts: { build: 'build', start: 'start', ...(workerRequired ? { worker: 'worker' } : {}) },
+      scripts: {
+        build: 'build',
+        start: 'start',
+        ...(workerRequired ? { worker: 'worker' } : {}),
+      },
     },
     bunderstack: { entry: args.entry, manifestVersion: 3 },
     resources: {
       database: {
         ...args.manifest.database,
         migrationMode: args.migrationMode,
-        tables: sortBy(args.manifest.database.tables, (entry) => entry.physicalName),
+        tables: sortBy(
+          args.manifest.database.tables,
+          (entry) => entry.physicalName,
+        ),
       },
       storage: {
         ...args.manifest.storage,
         buckets: sortBy(args.manifest.storage.buckets, (entry) => entry.name),
       },
-      ...(args.manifest.realtime.required ? { realtime: { required: true } } : {}),
+      ...(args.manifest.realtime.required
+        ? { realtime: { required: true } }
+        : {}),
     },
     environment: sortBy(args.manifest.environment, (entry) => entry.key),
     background: {
       worker: { required: workerRequired },
       jobs: sortBy(args.manifest.background.jobs, (entry) => entry.name),
       cron: sortBy(args.manifest.background.cron, (entry) => entry.name),
-      maintenance: sortBy(args.manifest.background.maintenance, (entry) => entry.name),
+      maintenance: sortBy(
+        args.manifest.background.maintenance,
+        (entry) => entry.name,
+      ),
     },
   })
 }
@@ -180,9 +267,15 @@ export function serializeBlueprint(value: BunderstackBlueprint): string {
     defaultStringType: 'PLAIN',
     lineWidth: 0,
   } as const
-  const source = stringify(parseBlueprintYaml(stringify(blueprint, options)), options)
-  return source.replace(/^(\s*schedule: )(.+)$/gm, (_match, prefix: string, value: string) => {
-    const schedule = value.startsWith('"') ? JSON.parse(value) : value
-    return `${prefix}${JSON.stringify(schedule)}`
-  })
+  const source = stringify(
+    parseBlueprintYaml(stringify(blueprint, options)),
+    options,
+  )
+  return source.replace(
+    /^(\s*schedule: )(.+)$/gm,
+    (_match, prefix: string, value: string) => {
+      const schedule = value.startsWith('"') ? JSON.parse(value) : value
+      return `${prefix}${JSON.stringify(schedule)}`
+    },
+  )
 }

package/src/cli.ts

@@ -25,11 +25,19 @@ export async function runCli(
     return 0
   }
   if (args[0] === '--version') {
-    io.stdout((await Bun.file(new URL('../package.json', import.meta.url)).json() as { version: string }).version)
+    io.stdout(
+      (
+        (await Bun.file(
+          new URL('../package.json', import.meta.url),
+        ).json()) as { version: string }
+      ).version,
+    )
     return 0
   }
   if (args[0] !== 'blueprint') {
-    io.stderr('Usage: bunderstack blueprint [directory] [--entry <path>] [--output <path>] [--check]')
+    io.stderr(
+      'Usage: bunderstack blueprint [directory] [--entry <path>] [--output <path>] [--check]',
+    )
     return 2
   }
   const options: GenerateBlueprintOptions = { directory: process.cwd() }

package/src/crud.ts

@@ -163,7 +163,11 @@ export function buildCrudRouter<TSchema extends Record<string, unknown>>(
         )
       }
 
-      const scope = scopeFor(tableAccess.readScope, { user, session, request: c.req.raw })
+      const scope = scopeFor(tableAccess.readScope, {
+        user,
+        session,
+        request: c.req.raw,
+      })
       if (
         scope &&
         !rowMatchesScope(rows[0] as Record<string, unknown>, scope)
@@ -240,7 +244,12 @@ export function buildCrudRouter<TSchema extends Record<string, unknown>>(
         user?.id ?? null,
       )
 
-      const scope = scopeFor(tableAccess.writeScope, { user, session, request: c.req.raw, body: body as Record<string, unknown> })
+      const scope = scopeFor(tableAccess.writeScope, {
+        user,
+        session,
+        request: c.req.raw,
+        body: body as Record<string, unknown>,
+      })
       const stamped = scope ? stampScope(values, scope) : values
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       const rows = await (db as any).insert(table).values(stamped).returning()
@@ -279,7 +288,11 @@ export function buildCrudRouter<TSchema extends Record<string, unknown>>(
         return apiError(c, ErrorCode.NOT_FOUND, 'Not found', 404)
       }
 
-      const readScope = scopeFor(tableAccess.readScope, { user, session, request: c.req.raw })
+      const readScope = scopeFor(tableAccess.readScope, {
+        user,
+        session,
+        request: c.req.raw,
+      })
       if (
         readScope &&
         !rowMatchesScope(existing[0] as Record<string, unknown>, readScope)
@@ -319,7 +332,12 @@ export function buildCrudRouter<TSchema extends Record<string, unknown>>(
         user?.id ?? null,
       )
 
-      const writeScope = scopeFor(tableAccess.writeScope, { user, session, request: c.req.raw, body: body as Record<string, unknown> })
+      const writeScope = scopeFor(tableAccess.writeScope, {
+        user,
+        session,
+        request: c.req.raw,
+        body: body as Record<string, unknown>,
+      })
       const stamped = writeScope ? stampScope(values, writeScope) : values
 
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -352,7 +370,11 @@ export function buildCrudRouter<TSchema extends Record<string, unknown>>(
         return apiError(c, ErrorCode.NOT_FOUND, 'Not found', 404)
       }
 
-      const scope = scopeFor(tableAccess.readScope, { user, session, request: c.req.raw })
+      const scope = scopeFor(tableAccess.readScope, {
+        user,
+        session,
+        request: c.req.raw,
+      })
       if (
         scope &&
         !rowMatchesScope(existing[0] as Record<string, unknown>, scope)

package/src/env.ts

@@ -22,9 +22,10 @@ export type BaseEnv = {
   BUNDERSTACK_CRON_SECRET?: string
 }
 
-type InferVars<T> = T extends Record<string, ZodType>
-  ? { [K in keyof T]: z.output<T[K]> }
-  : unknown
+type InferVars<T> =
+  T extends Record<string, ZodType>
+    ? { [K in keyof T]: z.output<T[K]> }
+    : unknown
 
 // Non-distributive so `ValidatedEnv<undefined>` is BaseEnv, not `never`.
 export type ValidatedEnv<TEnv extends EnvConfigInput | undefined> = [
@@ -113,8 +114,14 @@ export function validateEnv<TEnv extends EnvConfigInput | undefined>(
   if (isProduction && !source.AUTH_SECRET) {
     issues.push('AUTH_SECRET: required in production')
   }
-  if (isProduction && options.cronConfigured && !source.BUNDERSTACK_CRON_SECRET) {
-    issues.push('BUNDERSTACK_CRON_SECRET: required when cron is configured in production')
+  if (
+    isProduction &&
+    options.cronConfigured &&
+    !source.BUNDERSTACK_CRON_SECRET
+  ) {
+    issues.push(
+      'BUNDERSTACK_CRON_SECRET: required when cron is configured in production',
+    )
   }
   if (options.emailProvider === 'resend' && !source.RESEND_API_KEY) {
     issues.push("RESEND_API_KEY: required when email provider is 'resend'")

package/src/internal-tables.ts

@@ -121,7 +121,10 @@ const INTERNAL_TABLE_CANDIDATES = new Map<string, readonly unknown[]>([
     [bunderstackIdempotency, bunderstackIdempotencyPg],
   ],
   [getTableName(bunderstackJobs), [bunderstackJobs, bunderstackJobsPg]],
-  [getTableName(bunderstackCronRuns), [bunderstackCronRuns, bunderstackCronRunsPg]],
+  [
+    getTableName(bunderstackCronRuns),
+    [bunderstackCronRuns, bunderstackCronRunsPg],
+  ],
 ])
 
 /** Internal file-meta table matching the db's dialect. */

package/src/jobs/cron-router.ts

@@ -1,12 +1,12 @@
-import { Hono } from 'hono'
 import { and, eq, lt } from 'drizzle-orm'
+import { Hono } from 'hono'
 
 import type { AnyDb } from '../dialect'
 import type { BackgroundDefs } from './define'
 
+import { cronRunsTableFor } from '../internal-tables'
 import { verifyScheduleRequest } from './cron-auth'
 import { runCronSlot, runScheduledSlot } from './cron-runner'
-import { cronRunsTableFor } from '../internal-tables'
 
 const MAX_SLOT_AGE_MS = 60 * 60_000
 const MAX_FUTURE_SLOT_MS = 60_000
@@ -56,10 +56,7 @@ export function buildCronRouter(args: {
         slot,
         now: current,
       })
-      return c.json(
-        result,
-        result.status === 'running' ? 202 : 200,
-      )
+      return c.json(result, result.status === 'running' ? 202 : 200)
     } catch (error) {
       if (
         error instanceof Error &&
@@ -79,7 +76,14 @@ export function buildCronRouter(args: {
     if (!slotText || !Number.isSafeInteger(slot) || !signature) {
       return c.json({ error: 'invalid schedule signature' }, 401)
     }
-    if (!verifyScheduleRequest(args.secret, `maintenance:${name}`, slot, signature)) {
+    if (
+      !verifyScheduleRequest(
+        args.secret,
+        `maintenance:${name}`,
+        slot,
+        signature,
+      )
+    ) {
       return c.json({ error: 'invalid schedule signature' }, 401)
     }
     if (name !== 'storage-sweep') {

package/src/jobs/cron-runner.ts

@@ -22,11 +22,13 @@ export async function runScheduledSlot(args: {
   run: (scheduledFor: Date) => Promise<void> | void
   leaseMs?: number
   heartbeatIntervalMs?: number
+  heartbeatCleanupTimeoutMs?: number
 }): Promise<CronRunResult> {
   const { db, taskId, schedule, slot, now, run } = args
   const leaseMs = args.leaseMs ?? LEASE_MS
   const heartbeatIntervalMs =
     args.heartbeatIntervalMs ?? Math.max(1, Math.floor(leaseMs / 4))
+  const heartbeatCleanupTimeoutMs = args.heartbeatCleanupTimeoutMs ?? 1_000
 
   if (slot % 60_000 !== 0 || !cronMatches(parseCron(schedule), slot)) {
     throw new Error('[bunderstack] cron slot does not match its schedule')
@@ -45,9 +47,12 @@ export async function runScheduledSlot(args: {
       startedAt: now,
     })
     .onConflictDoNothing({ target: [t.taskId, t.scheduledAt] })
-    .returning({ taskId: t.taskId })
+    .returning({ taskId: t.taskId, attempts: t.attempts })
 
-  if (!inserted[0]) {
+  let ownershipAttempt: number
+  if (inserted[0]) {
+    ownershipAttempt = Number(inserted[0].attempts)
+  } else {
     const existing = await db
       .select({ status: t.status, lockedUntil: t.lockedUntil })
       .from(t)
@@ -74,42 +79,75 @@ export async function runScheduledSlot(args: {
           or(eq(t.status, 'failed'), lt(t.lockedUntil, now)),
         ),
       )
-      .returning({ taskId: t.taskId })
-    if (!reclaimed[0]) return { status: 'running' }
+      .returning({ taskId: t.taskId, attempts: t.attempts })
+    const reclaimedRow = reclaimed[0]
+    if (!reclaimedRow) return { status: 'running' }
+    ownershipAttempt = Number(reclaimedRow.attempts)
   }
 
   let heartbeatTimer: Timer | undefined
-  const stopHeartbeat = () => {
+  let heartbeatInFlight: Promise<void> | undefined
+  let heartbeatStopped = false
+
+  const scheduleHeartbeat = () => {
+    heartbeatTimer = setTimeout(() => {
+      heartbeatTimer = undefined
+      if (heartbeatStopped) return
+
+      heartbeatInFlight = (async () => {
+        try {
+          const renewUntil = Date.now() + leaseMs
+          await db
+            .update(t)
+            .set({ lockedUntil: renewUntil })
+            .where(
+              and(
+                eq(t.taskId, taskId),
+                eq(t.scheduledAt, slot),
+                eq(t.status, 'running'),
+                eq(t.startedAt, now),
+                eq(t.attempts, ownershipAttempt),
+              ),
+            )
+        } catch {
+          // Best effort renewal
+        }
+      })()
+
+      void heartbeatInFlight.finally(() => {
+        heartbeatInFlight = undefined
+        if (!heartbeatStopped) scheduleHeartbeat()
+      })
+    }, heartbeatIntervalMs)
+  }
+
+  const stopHeartbeat = async () => {
+    heartbeatStopped = true
     if (heartbeatTimer) {
-      clearInterval(heartbeatTimer)
+      clearTimeout(heartbeatTimer)
       heartbeatTimer = undefined
     }
-  }
+    const inFlight = heartbeatInFlight
+    if (!inFlight) return
 
-  heartbeatTimer = setInterval(async () => {
+    let cleanupTimer: Timer | undefined
     try {
-      const renewUntil = Date.now() + leaseMs
-      await db
-        .update(t)
-        .set({ lockedUntil: renewUntil })
-        .where(
-          and(
-            eq(t.taskId, taskId),
-            eq(t.scheduledAt, slot),
-            eq(t.status, 'running'),
-            eq(t.startedAt, now),
-          ),
-        )
-    } catch {
-      // Best effort renewal
+      await Promise.race([
+        inFlight,
+        new Promise<void>((resolve) => {
+          cleanupTimer = setTimeout(resolve, heartbeatCleanupTimeoutMs)
+        }),
+      ])
+    } finally {
+      if (cleanupTimer) clearTimeout(cleanupTimer)
     }
-  }, heartbeatIntervalMs)
+  }
+
+  scheduleHeartbeat()
 
   try {
     await run(new Date(slot))
 
-    stopHeartbeat()
-
     const updated = await db
       .update(t)
       .set({ status: 'succeeded', lockedUntil: null, finishedAt: Date.now() })
@@ -119,6 +157,7 @@ export async function runScheduledSlot(args: {
           eq(t.scheduledAt, slot),
           eq(t.status, 'running'),
           eq(t.startedAt, now),
+          eq(t.attempts, ownershipAttempt),
         ),
       )
       .returning({ taskId: t.taskId })
@@ -131,8 +170,6 @@ export async function runScheduledSlot(args: {
 
     return { status: 'succeeded' }
   } catch (error) {
-    stopHeartbeat()
-
     const message = error instanceof Error ? error.message : String(error)
     await db
       .update(t)
@@ -148,11 +185,12 @@ export async function runScheduledSlot(args: {
           eq(t.scheduledAt, slot),
           eq(t.status, 'running'),
           eq(t.startedAt, now),
+          eq(t.attempts, ownershipAttempt),
         ),
       )
     throw error
   } finally {
-    stopHeartbeat()
+    await stopHeartbeat()
   }
 }
 
@@ -165,6 +203,7 @@ export async function runCronSlot(args: {
   now: number
   leaseMs?: number
   heartbeatIntervalMs?: number
+  heartbeatCleanupTimeoutMs?: number
 }): Promise<CronRunResult> {
   const definition = args.defs[args.name]
   if (!definition || definition.kind !== 'cron') {
@@ -178,6 +217,7 @@ export async function runCronSlot(args: {
     now: args.now,
     leaseMs: args.leaseMs,
     heartbeatIntervalMs: args.heartbeatIntervalMs,
+    heartbeatCleanupTimeoutMs: args.heartbeatCleanupTimeoutMs,
     run: (scheduledFor) =>
       definition.handler({ scheduledFor }, args.ctx as never),
   })

package/src/jobs/index.ts

@@ -30,7 +30,11 @@ export type { CronRunResult } from './cron-runner'
 export { buildCronRouter } from './cron-router'
 export { signScheduleRequest, verifyScheduleRequest } from './cron-auth'
 export { startJobWorker } from './runtime'
-export type { StartWorkerOptions, RunWorkerOptions, WorkerHandle } from './runtime'
+export type {
+  StartWorkerOptions,
+  RunWorkerOptions,
+  WorkerHandle,
+} from './runtime'
 export { startLocalCronScheduler } from './local-cron'
 export type {
   LocalCronScheduler,

package/src/jobs/worker.ts

@@ -4,11 +4,7 @@ import { and, eq, inArray, is, isNotNull, lt, lte, sql } from 'drizzle-orm'
 import { PgDatabase } from 'drizzle-orm/pg-core'
 
 import type { AnyDb } from '../dialect'
-import type {
-  AnyJobDefinition,
-  JobsDefs,
-  JobsRuntimeFacade,
-} from './define'
+import type { AnyJobDefinition, JobsDefs, JobsRuntimeFacade } from './define'
 
 import { jobsTableFor } from '../internal-tables'
 import { backoffMs, DEFAULT_RETRIES, DEFAULT_TIMEOUT_MS } from './define'
@@ -77,7 +73,11 @@ export function createJobRunner(deps: {
       })
       .from(t)
       .where(
-        and(eq(t.status, 'running'), isNotNull(t.lockedUntil), lt(t.lockedUntil, now)),
+        and(
+          eq(t.status, 'running'),
+          isNotNull(t.lockedUntil),
+          lt(t.lockedUntil, now),
+        ),
       )
     for (const row of expired) {
       const def = defs[row.type]
@@ -148,8 +148,11 @@ export function createJobRunner(deps: {
     // PG: lock the selected rows so concurrent replicas skip them. SQLite's
     // single-writer model makes the one-statement UPDATE atomic on its own.
     const sub = is(db, PgDatabase)
-      ? (pendingIds as unknown as { for: (m: string, o: object) => typeof pendingIds })
-          .for('update', { skipLocked: true })
+      ? (
+          pendingIds as unknown as {
+            for: (m: string, o: object) => typeof pendingIds
+          }
+        ).for('update', { skipLocked: true })
       : pendingIds
     const rows: JobRow[] = await db
       .update(t)

package/src/list-query.ts

@@ -16,8 +16,8 @@ import {
 } from 'drizzle-orm'
 import { PgTable } from 'drizzle-orm/pg-core'
 
-import type { AnyDb } from './dialect'
 import type { ResolvedTableAccess, SortOrder } from './access'
+import type { AnyDb } from './dialect'
 
 import { ErrorCode, ListQueryError } from './errors'
 
@@ -282,9 +282,7 @@ export function encodeCursor(payload: CursorPayload): string {
 
 export function decodeCursor(cursor: string): CursorPayload {
   try {
-    const parsed = JSON.parse(
-      Buffer.from(cursor, 'base64url').toString('utf8'),
-    )
+    const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'))
     if (!isCursorPayload(parsed)) {
       throw new Error('invalid cursor shape')
     }

package/src/manifest.ts

@@ -5,13 +5,14 @@ import type { Dialect } from './dialect'
 import type { EnvConfigInput } from './env'
 import type { JobsDefs } from './jobs/define'
 import type { ResolvedBucket, ResolvedStorageBuckets } from './storage/buckets'
-import { parseCron } from './jobs/cron'
+
 import {
   bunderstackCronRuns,
   bunderstackFiles,
   bunderstackIdempotency,
   bunderstackJobs,
 } from './internal-tables'
+import { parseCron } from './jobs/cron'
 
 export type ManifestEnvVar = {
   key: string
@@ -47,8 +48,12 @@ const nonEmpty = z.string().min(1)
 const migrationDirectory = nonEmpty.refine(
   (value) =>
     value.startsWith('/') ||
-    (!value.includes('\\') && value.split('/').every((part) => part !== '..' && part !== '')),
-  { message: 'migrationsDirectory must be an absolute path or a relative path without traversal' },
+    (!value.includes('\\') &&
+      value.split('/').every((part) => part !== '..' && part !== '')),
+  {
+    message:
+      'migrationsDirectory must be an absolute path or a relative path without traversal',
+  },
 )
 const cronSchedule = nonEmpty.refine(
   (value) => {
@@ -85,7 +90,10 @@ const manifestSchema = z
         defaultBucket: nonEmpty,
         buckets: z.array(
           z
-            .object({ name: nonEmpty, visibility: z.enum(['public', 'private']) })
+            .object({
+              name: nonEmpty,
+              visibility: z.enum(['public', 'private']),
+            })
             .strict(),
         ),
       })
@@ -133,13 +141,16 @@ function sortBy<T>(entries: readonly T[], key: (entry: T) => string): T[] {
 function rejectDuplicates(collection: string, values: readonly string[]): void {
   const seen = new Set<string>()
   for (const value of values) {
-    if (seen.has(value)) throw new Error(`[bunderstack] duplicate ${collection} "${value}"`)
+    if (seen.has(value))
+      throw new Error(`[bunderstack] duplicate ${collection} "${value}"`)
     seen.add(value)
   }
 }
 
 function describeTables(schema: Record<string, unknown>) {
-  const systemNames = new Set<string>(systemTables().map((table) => table.physicalName))
+  const systemNames = new Set<string>(
+    systemTables().map((table) => table.physicalName),
+  )
   return sortBy(
     Object.entries(schema).flatMap(([exportName, value]) =>
       isTable(value) && !systemNames.has(getTableName(value))
@@ -163,13 +174,21 @@ function describeSection(
 
 function systemTables() {
   return [
-    { exportName: '_system.files', physicalName: getTableName(bunderstackFiles), system: true },
+    {
+      exportName: '_system.files',
+      physicalName: getTableName(bunderstackFiles),
+      system: true,
+    },
     {
       exportName: '_system.idempotency',
       physicalName: getTableName(bunderstackIdempotency),
       system: true,
     },
-    { exportName: '_system.jobs', physicalName: getTableName(bunderstackJobs), system: true },
+    {
+      exportName: '_system.jobs',
+      physicalName: getTableName(bunderstackJobs),
+      system: true,
+    },
     {
       exportName: '_system.scheduledRuns',
       physicalName: getTableName(bunderstackCronRuns),
@@ -180,13 +199,34 @@ function systemTables() {
 
 export function parseManifest(value: unknown): BunderstackManifest {
   const manifest = manifestSchema.parse(value) as BunderstackManifest
-  rejectDuplicates('database physical table', manifest.database.tables.map((entry) => entry.physicalName))
-  rejectDuplicates('database export table', manifest.database.tables.map((entry) => entry.exportName))
-  rejectDuplicates('storage bucket', manifest.storage.buckets.map((entry) => entry.name))
-  rejectDuplicates('environment key', manifest.environment.map((entry) => entry.key))
-  rejectDuplicates('background job', manifest.background.jobs.map((entry) => entry.name))
-  rejectDuplicates('background cron', manifest.background.cron.map((entry) => entry.name))
-  rejectDuplicates('background maintenance', manifest.background.maintenance.map((entry) => entry.name))
+  rejectDuplicates(
+    'database physical table',
+    manifest.database.tables.map((entry) => entry.physicalName),
+  )
+  rejectDuplicates(
+    'database export table',
+    manifest.database.tables.map((entry) => entry.exportName),
+  )
+  rejectDuplicates(
+    'storage bucket',
+    manifest.storage.buckets.map((entry) => entry.name),
+  )
+  rejectDuplicates(
+    'environment key',
+    manifest.environment.map((entry) => entry.key),
+  )
+  rejectDuplicates(
+    'background job',
+    manifest.background.jobs.map((entry) => entry.name),
+  )
+  rejectDuplicates(
+    'background cron',
+    manifest.background.cron.map((entry) => entry.name),
+  )
+  rejectDuplicates(
+    'background maintenance',
+    manifest.background.maintenance.map((entry) => entry.name),
+  )
   return manifest
 }
 
@@ -210,14 +250,20 @@ export function buildManifest(args: {
       ? [{ key: 'SMTP_URL', required: true, scope: 'server' as const }]
       : []),
   ]
-  rejectDuplicates('environment key', environment.map((entry) => entry.key))
+  rejectDuplicates(
+    'environment key',
+    environment.map((entry) => entry.key),
+  )
 
   return parseManifest({
     version: 3,
     database: {
       dialect: args.dialect,
       migrationsDirectory: args.migrationsDirectory,
-      tables: sortBy([...systemTables(), ...describeTables(args.schema)], (entry) => entry.physicalName),
+      tables: sortBy(
+        [...systemTables(), ...describeTables(args.schema)],
+        (entry) => entry.physicalName,
+      ),
     },
     storage: {
       defaultBucket: args.storage.defaultBucket,
@@ -249,7 +295,11 @@ export function buildManifest(args: {
         (entry) => entry.name,
       ),
       maintenance: [
-        { name: 'storage-sweep', schedule: '0 4 * * *', timezone: 'UTC' as const },
+        {
+          name: 'storage-sweep',
+          schedule: '0 4 * * *',
+          timezone: 'UTC' as const,
+        },
       ],
     },
   })

package/src/storage/buckets.ts

@@ -266,7 +266,8 @@ export function resolveBuckets(
   input: StorageConfigInput | undefined,
   env: Record<string, string | undefined> = process.env,
 ): ResolvedStorageBuckets {
-  const sharedBackend = platformS3Backend(env) ?? resolveSharedBackend(input, env)
+  const sharedBackend =
+    platformS3Backend(env) ?? resolveSharedBackend(input, env)
   const bucketsInput = input?.buckets
 
   const declaredNames = bucketsInput ? Object.keys(bucketsInput) : []

package/src/storage/file-meta.ts

@@ -29,8 +29,8 @@
 
 import { eq, and, lt, sql } from 'drizzle-orm'
 
-import type { AnyDb } from '../dialect'
 import type { ScopeMap } from '../access'
+import type { AnyDb } from '../dialect'
 
 import { rowMatchesScope } from '../access'
 import { bunderstackFiles, filesTableFor } from '../internal-tables'

package/src/storage/router.ts

@@ -27,11 +27,7 @@ import {
   sumReadySize,
   type FileMetaRow,
 } from './file-meta'
-import {
-  parseTransformSpec,
-  transformHash,
-  transformImage,
-} from './thumbnails'
+import { parseTransformSpec, transformHash, transformImage } from './thumbnails'
 
 export interface BucketStorageRouterOptions {
   registry: BucketStorageRegistry
@@ -379,7 +375,7 @@ export function buildBucketStorageRouter(
     if (!entry) return apiError(c, ErrorCode.NOT_FOUND, 'Unknown bucket', 404)
     const { bucket, adapter } = entry
 
-    const mountPrefix = c.req.routePath.replace(/\/:[^\/]+\/\*$/, '')
+    const mountPrefix = c.req.routePath.replace(/\/:[^/]+\/\*$/, '')
     const id = c.req.path.slice(`${mountPrefix}/${bucketName}/`.length)
     const fileId = `${bucketName}/${id}`
 

package/src/storage/s3.ts

@@ -39,11 +39,17 @@ export class S3StorageAdapter implements StorageAdapter {
   }
 
   async get(fileId: string): Promise<Response> {
-    const exists = await this.client.exists(fileId)
-    if (!exists) return new Response('Not found', { status: 404 })
+    // `stat` (a HEAD, same cost as `exists`) is the only way to learn the
+    // stored Content-Type: a lazily-constructed `client.file(key)` reports
+    // `type: ""` — it never stats, and unlike `Bun.file` it does not guess
+    // from the extension either.
+    const info = await this.stat(fileId)
+    if (!info) return new Response('Not found', { status: 404 })
     const file = this.client.file(fileId)
     return new Response(file.stream(), {
-      headers: { 'Content-Type': file.type ?? 'application/octet-stream' },
+      headers: {
+        'Content-Type': info.contentType || 'application/octet-stream',
+      },
     })
   }
 

package/src/trpc.ts

@@ -5,9 +5,9 @@ import superjson from 'superjson'
 import type { AccessUser } from './access'
 import type { DbFor } from './db'
 import type { EmailFacade } from './email'
+import type { StorageFacade } from './index'
 import type { JobsRuntimeFacade } from './jobs/index'
 import type { RealtimeFacade } from './realtime/facade'
-import type { StorageFacade } from './index'
 
 export type TRPCContext<
   TSchema extends Record<string, unknown>,