@omg-dev/server 0.4.24

package/src/index.ts

@@ -0,0 +1,702 @@
+import path from "node:path"
+import fs from "node:fs"
+import type { Schema } from "@omg-dev/schema"
+import { createAuthMiddleware, type AuthResult } from "@omg-dev/auth"
+import { ctxStore, ctx } from "./ctx.ts"
+import { openDb, dbProxy, setDbInstance, type VibesDb } from "./db.ts"
+import { migrate, registerScopes } from "./migrator.ts"
+import { loadRoutes, handleRequest, clearModuleCache, type Route, type RouteMap } from "./dispatcher.ts"
+import { buildAutoCrudRoutes } from "./auto-crud.ts"
+import { setSubscriptionSchema } from "./subscriptions.ts"
+import {
+  loadTriggersFromFile,
+  registerTriggers,
+  setCronDriver,
+  dispatchHandler,
+  dispatchStorageEvent,
+  devInspectTriggers,
+  devInspectDeliveries,
+  devInspectEvents,
+} from "./triggers.ts"
+import {
+  loadWorkflowsFromFile,
+  registerWorkflows,
+  buildWorkflowEndpoint,
+  handleWorkflowRequest,
+  devInspectWorkflowRuns,
+  type WorkflowEntry,
+} from "./workflows.ts"
+import { storage } from "./storage.ts"
+import {
+  ensureNotificationIndexes,
+  notificationSystemCollectionNames,
+  notificationSystemSchema,
+  notificationsConfigHandler,
+  notificationsCreateHandler,
+  notificationsReadHandler,
+  notificationServiceWorkerHandler,
+  notificationsSubscribeHandler,
+  notificationsListHandler,
+  notificationsUnreadCountHandler,
+  notificationsUnsubscribeHandler,
+  notify,
+  withNotificationSystemSchema,
+  type NotifyInput,
+} from "./notifications.ts"
+
+export { ctx } from "./ctx.ts"
+export { dbProxy as db } from "./db.ts"
+export { VibesAuthRequiredError } from "./db.ts"
+export { VibesHttpError } from "./http-error.ts"
+export type { VibesDb, GetAllOpts } from "./db.ts"
+export type { VibesCtx } from "./ctx.ts"
+export type { Route } from "./dispatcher.ts"
+export { addClient, removeClient, invalidate, clientCount } from "./broker.ts"
+export {
+  addSubClient,
+  removeSubClient,
+  handleSubMessage,
+  notifyCollectionChange,
+  notifyRowChange,
+  subClientCount,
+  subscriptionCount,
+  setSubscriptionSchema,
+  setSubscriptionRingCap,
+  setMaxSubsPerClient,
+  type SubClient,
+  type SubClientMessage,
+  type SubServerMessage,
+} from "./subscriptions.ts"
+export {
+  validatePredicate,
+  compileToSql,
+  compileToJs,
+  PredicateValidationError,
+  type Predicate,
+  type Literal,
+  type CompiledSql,
+} from "./predicate.ts"
+export { createAuthMiddleware } from "@omg-dev/auth"
+export { migrate, registerScopes } from "./migrator.ts"
+export { buildAutoCrudRoutes } from "./auto-crud.ts"
+// Schema-aware row decoders (parse JSON array columns, coerce booleans). The
+// auto-CRUD read handlers run every returned row through these; hand-written
+// db.raw() read paths must do the same or array columns leak to the client as
+// raw JSON strings (see control-plane projects.get / sessionMarkers crash).
+export { decodeRow, decodeRows } from "./codec.ts"
+export {
+  cron,
+  on,
+  emit,
+  schedule,
+  cancel,
+  registerTriggers,
+  loadTriggersFromFile,
+  dispatchHandler,
+  listTriggers,
+  clearTriggers,
+  setCronDriver,
+  devInspectTriggers,
+  devInspectDeliveries,
+  devInspectEvents,
+  type CronHandler,
+  type EventHandler,
+  type CronDriver,
+} from "./triggers.ts"
+// Build/boot-time trigger scanning — shared by vite-plugin (build) and
+// non-vite hosts that write .vibes/triggers.json themselves at boot.
+export {
+  scanTriggers,
+  extractTriggers,
+  writeTriggersManifest,
+  TriggerScanError,
+  type ScannedTrigger,
+  type TriggerKind,
+} from "./trigger-scan.ts"
+export {
+  workflow,
+  startWorkflow,
+  registerWorkflows,
+  loadWorkflowsFromFile,
+  listWorkflows,
+  clearWorkflows,
+  devInspectWorkflowRuns,
+  workflowServiceName,
+  type StepContext,
+  type WorkflowFn,
+  type WorkflowEntry,
+  type StartWorkflowOptions,
+} from "./workflows.ts"
+export {
+  storage,
+  _verifyDevStorageToken,
+  _devStorageWrite,
+  _devStorageRead,
+  type StorageScope,
+  type UploadUrlOptions,
+  type DownloadUrlOptions,
+  type ListOptions,
+  type PresignedUploadResult,
+  type PresignedDownloadResult,
+  type StorageItem,
+  type StorageEvent,
+  type StorageEventHandler,
+} from "./storage.ts"
+export {
+  billing,
+  usd,
+  type Billing,
+  type EnsureCustomerResult,
+  type CheckResult,
+  type TrackResult,
+  type GrantResult,
+  type BalanceResult,
+  type GrantOptions,
+  type CheckoutOptions,
+  type CheckoutResult,
+} from "./billing.ts"
+export {
+  notify,
+  notificationSystemSchema,
+  type NotifyInput,
+} from "./notifications.ts"
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export interface VibesServerOptions {
+  root: string
+  db: string
+  /**
+   * Auth posture. A mode string ("vibes" verifies a Bearer JWT via JWKS;
+   * "local" is anonymous), OR a custom middleware function for hosts that need
+   * bespoke verification (e.g. the control-plane accepts a second token family
+   * on a scoped route surface). The function receives the request and returns
+   * the resolved identity, or null when anonymous — same contract as the
+   * mode-string middleware that createAuthMiddleware produces.
+   */
+  auth?: "vibes" | "local" | ((req: Request) => Promise<AuthResult | null>)
+  routes?: Route[]
+  /**
+   * Pre-bundled trigger entries from .vibes/triggers.generated.ts (prod).
+   * When provided, the trigger registry skips reading .vibes/triggers.json
+   * and dynamic-importing handler modules — module paths in the JSON are
+   * build-time absolutes that don't resolve at runtime in a bundled
+   * deploy. Dev mode (no `triggers` passed) still uses the JSON-based
+   * loader since vite-plugin can dynamic-import via the dev server.
+   */
+  triggers?: BundledTrigger[]
+  /**
+   * Which machinery fires cron() handlers. Default "orchestrator": the
+   * platform's ticker + dispatcher POST /_vibes/dispatch into this server —
+   * correct for orchestrator-managed deploys, but a standalone container
+   * (control-plane, self-host bundle) never receives those dispatches and
+   * its crons silently never fire. Set "in-process" there: the same
+   * setInterval scheduler dev mode uses, armed at trigger registration.
+   * Only affects cron — emit()/schedule() routing still follows VIBES_MODE.
+   * Env equivalent: VIBES_CRON_DRIVER.
+   */
+  cron?: "orchestrator" | "in-process"
+  /**
+   * Pre-bundled workflow entries from .vibes/workflows.generated.ts (prod).
+   * Same dev/prod split as `triggers`: when omitted, the registry reads
+   * .vibes/workflows.json and dynamic-imports handler modules.
+   */
+  workflows?: WorkflowEntry[]
+  staticDir?: string
+  schema?: Schema
+  /**
+   * When false, skip DDL migrations at startup — but still register user-scoped
+   * tables so row-level filtering by _owner keeps working. Used by the
+   * bundled production server: migrations ran at build time against the
+   * seeded .vibes/data.db and we don't want to re-diff sqlite_master on every
+   * cold start. Defaults to true.
+   */
+  migrate?: boolean
+  /**
+   * When false, do NOT register the generic auto-CRUD REST routes
+   * (`GET/POST/PUT/DELETE /api/<collection>` + `/:id`). The schema is still
+   * used for migrations, scope registration, and the live-query subscription
+   * layer — only the generic REST surface is withheld. Defaults to true (user
+   * apps rely on it via useCollection). The control-plane sets this false: its
+   * tables aren't `scope:"user"`, so an open auto-CRUD route would serve every
+   * row to anyone; all dashboard reads/writes go through scoped custom
+   * functions instead.
+   */
+  autoCrud?: boolean
+}
+
+// Shape produced by vite-plugin's triggers.generated.ts. Mirrors the
+// internal TriggerEntry shape in triggers.ts but is the public type the
+// generated file imports.
+export interface BundledTrigger {
+  handler: string
+  kind: "cron" | "on"
+  key: string
+  module: string
+  exportName: string
+  mod: Record<string, unknown>
+}
+
+export interface VibesServerInstance {
+  apiHandler: (req: Request) => Promise<Response>
+  fetch: (req: Request) => Promise<Response>
+  /**
+   * Re-run DDL migrations and rebuild the auto-CRUD route table. Pass
+   * `newSchema` to swap the active schema (the dev plugin's HMR handler
+   * calls this when `schema.ts` changes); omit to re-migrate the current
+   * one. Lazily opens the DB the first time collections appear, so a
+   * server that booted with empty collections can transition to having
+   * collections without a restart — this is what makes the
+   * "template starts empty → agent writes schema.ts" flow work in dev.
+   */
+  migrate: (newSchema?: Schema) => void
+  reloadFunctions: () => void
+  /**
+   * Re-read .vibes/triggers.json and re-register cron + on handlers. Called
+   * by the vite-plugin's HMR handler when a functions/*.ts file changes.
+   */
+  reloadTriggers: () => Promise<void>
+  /** Same as reloadTriggers, for .vibes/workflows.json (dev HMR). */
+  reloadWorkflows: () => Promise<void>
+  close: () => void
+}
+
+// ── Built-in storage presign route handler ───────────────────────────────────
+//
+// Exposed at POST /api/_storage/presign so client-side <VibesUpload /> +
+// useUpload() don't have to wire any boilerplate in the user app. The handler
+// reads ctx.userId (set by the auth middleware) and refuses requests without
+// a verified user unless scope:"app" is explicitly requested.
+
+interface PresignRequestBody {
+  action?: "put" | "get"
+  key?: string
+  contentType?: string
+  scope?: "user" | "app"
+}
+
+async function storagePresignHandler(req: Request): Promise<Response> {
+  let body: PresignRequestBody
+  try {
+    body = (await req.json()) as PresignRequestBody
+  } catch {
+    return Response.json({ error: "invalid JSON body" }, { status: 400 })
+  }
+  const action = body.action ?? "put"
+  if (action !== "put" && action !== "get") {
+    return Response.json({ error: `unknown action: ${action}` }, { status: 400 })
+  }
+  if (!body.key || typeof body.key !== "string") {
+    return Response.json({ error: "key required" }, { status: 400 })
+  }
+  const scope = body.scope ?? "user"
+  if (scope !== "user" && scope !== "app") {
+    return Response.json({ error: `unknown scope: ${scope}` }, { status: 400 })
+  }
+  if (scope === "user" && !ctx.userId) {
+    return Response.json(
+      { error: "auth required for scope:user — sign in or pass scope:'app'." },
+      { status: 401 },
+    )
+  }
+  try {
+    if (action === "put") {
+      const out = await storage.uploadUrl({
+        key: body.key,
+        contentType: body.contentType,
+        scope,
+      })
+      return Response.json(out)
+    }
+    const out = await storage.downloadUrl(body.key, { scope })
+    return Response.json(out)
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    return Response.json({ error: msg }, { status: 500 })
+  }
+}
+
+// ── Built-in storage notify route ───────────────────────────────────────────
+//
+// POST /api/_storage/notify is fired by the SDK (useUpload, VibesUpload) after
+// a successful PUT/DELETE round-trip. Body identifies the file + action; this
+// handler fans out to every `storage.onUpload` / `onDelete` registered via
+// functions/*.ts. Runs in-process — no orchestrator round-trip.
+//
+// Auth: same posture as presign. ctx.userId is read to attribute the event;
+// the handler is free to refuse if scope:"user" with no authed user. We
+// don't reject here — handlers may legitimately fire under scope:"app".
+
+interface StorageNotifyBody {
+  action?: "upload" | "delete"
+  key?: string
+  size?: number
+  contentType?: string
+  scope?: "user" | "app"
+}
+
+async function storageNotifyHandler(req: Request): Promise<Response> {
+  let body: StorageNotifyBody
+  try {
+    body = (await req.json()) as StorageNotifyBody
+  } catch {
+    return Response.json({ error: "invalid JSON body" }, { status: 400 })
+  }
+  const action = body.action ?? "upload"
+  if (action !== "upload" && action !== "delete") {
+    return Response.json({ error: `unknown action: ${action}` }, { status: 400 })
+  }
+  if (!body.key || typeof body.key !== "string") {
+    return Response.json({ error: "key required" }, { status: 400 })
+  }
+  const scope = body.scope ?? "user"
+  const kind = action === "upload" ? "storage:upload" : "storage:delete"
+  try {
+    const fired = await dispatchStorageEvent(kind, {
+      key: body.key,
+      size: body.size,
+      contentType: body.contentType,
+      userId: ctx.userId ?? null,
+      scope,
+    })
+    return Response.json({ ok: true, handlersFired: fired })
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    return Response.json({ error: msg }, { status: 500 })
+  }
+}
+
+// ── createVibesServer ─────────────────────────────────────────────────────────
+
+export async function createVibesServer(opts: VibesServerOptions): Promise<VibesServerInstance> {
+  const { root, db: dbPath } = opts
+  let currentSchema: Schema | undefined = withNotificationSystemSchema(opts.schema)
+
+  // Track function-file routes separately from auto-CRUD so the route table
+  // can be rebuilt when collections are added or removed via HMR — without
+  // dropping user-authored handlers in the process.
+  //
+  // Source of explicit routes:
+  //   - `opts.routes` (prod-bundled deploys): preloaded with `mod` refs;
+  //     never changes after boot.
+  //   - `.vibes/routes.json` on disk (dev): regenerated by the vite plugin
+  //     whenever a `functions/**.ts` file is added/edited/removed. The
+  //     dev path re-reads on every `reloadFunctions()` call so newly
+  //     scaffolded routes (e.g. pi creates `functions/api/chat.ts`
+  //     after the server is already running) actually become reachable
+  //     without restarting the dev server.
+  function loadExplicitRoutes(): RouteMap {
+    if (opts.routes) return loadRoutes(opts.routes)
+    const routesJsonPath = path.join(root, ".vibes", "routes.json")
+    if (!fs.existsSync(routesJsonPath)) return []
+    const raw = JSON.parse(fs.readFileSync(routesJsonPath, "utf-8")) as Route[]
+    return loadRoutes(raw)
+  }
+
+  let explicitRoutes: RouteMap = loadExplicitRoutes()
+  let routes: RouteMap = []
+
+  // Touching dbProxy at runtime throws when no DB has been opened —
+  // intentional; a no-collection deploy shouldn't have code paths that
+  // reach it. We open lazily so the empty → non-empty transition works.
+  let dbInstance: VibesDb | null = null
+  function ensureDb(): VibesDb {
+    if (dbInstance) return dbInstance
+    const resolvedDbPath = path.isAbsolute(dbPath) ? dbPath : path.join(root, dbPath)
+    dbInstance = openDb(resolvedDbPath)
+    setDbInstance(dbInstance)
+    return dbInstance
+  }
+
+  function hasCollections(s: Schema | undefined): s is Schema {
+    return !!s?.collections && Object.keys(s.collections).length > 0
+  }
+
+  // Built-in storage routes. Same precedence rule as auto-CRUD: a
+  // user-authored functions/_storage.ts route with the same (method, path)
+  // overrides this default.
+  const storageBuiltinRoutes: Route[] = [
+    {
+      method: "POST",
+      path: "/api/_storage/presign",
+      module: "@omg-dev/server/storage-presign",
+      handler: "inline",
+      inlineHandler: storagePresignHandler,
+    },
+    {
+      method: "POST",
+      path: "/api/_storage/notify",
+      module: "@omg-dev/server/storage-notify",
+      handler: "inline",
+      inlineHandler: storageNotifyHandler,
+    },
+  ]
+  const notificationBuiltinRoutes: Route[] = [
+    {
+      method: "GET",
+      path: "/api/_notifications/config",
+      module: "@omg-dev/server/notifications-config",
+      handler: "inline",
+      inlineHandler: notificationsConfigHandler,
+    },
+    {
+      method: "GET",
+      path: "/api/_notifications/list",
+      module: "@omg-dev/server/notifications-list",
+      handler: "inline",
+      inlineHandler: notificationsListHandler,
+    },
+    {
+      method: "GET",
+      path: "/api/_notifications/unread-count",
+      module: "@omg-dev/server/notifications-unread-count",
+      handler: "inline",
+      inlineHandler: notificationsUnreadCountHandler,
+    },
+    {
+      method: "POST",
+      path: "/api/_notifications/subscribe",
+      module: "@omg-dev/server/notifications-subscribe",
+      handler: "inline",
+      inlineHandler: notificationsSubscribeHandler,
+    },
+    {
+      method: "POST",
+      path: "/api/_notifications/unsubscribe",
+      module: "@omg-dev/server/notifications-unsubscribe",
+      handler: "inline",
+      inlineHandler: notificationsUnsubscribeHandler,
+    },
+    {
+      method: "POST",
+      path: "/api/_notifications/read",
+      module: "@omg-dev/server/notifications-read",
+      handler: "inline",
+      inlineHandler: notificationsReadHandler,
+    },
+    {
+      method: "POST",
+      path: "/api/_notifications/create",
+      module: "@omg-dev/server/notifications-create",
+      handler: "inline",
+      inlineHandler: notificationsCreateHandler,
+    },
+  ]
+
+  // Function-file routes take precedence — when a user-authored handler
+  // exists at the same (method, path), the auto-route is skipped so custom
+  // logic always wins.
+  function rebuildRoutes(): void {
+    const explicit = new Set(explicitRoutes.map(r => `${r.method} ${r.path}`))
+    const builtinKeys = new Set([
+      ...storageBuiltinRoutes.map(r => `${r.method} ${r.path}`),
+      ...notificationBuiltinRoutes.map(r => `${r.method} ${r.path}`),
+    ])
+    const builtinStorage = storageBuiltinRoutes.filter(
+      r => !explicit.has(`${r.method} ${r.path}`),
+    )
+    const builtinNotifications = notificationBuiltinRoutes.filter(
+      r => !explicit.has(`${r.method} ${r.path}`),
+    )
+    if (hasCollections(currentSchema) && opts.autoCrud !== false) {
+      const auto = buildAutoCrudRoutes(currentSchema).filter(
+        r => {
+          if (explicit.has(`${r.method} ${r.path}`) || builtinKeys.has(`${r.method} ${r.path}`)) return false
+          const collection = r.path.split("/")[2]
+          return !notificationSystemCollectionNames.has(collection)
+        },
+      )
+      routes = [...auto, ...builtinStorage, ...builtinNotifications, ...explicitRoutes]
+    } else {
+      routes = [...builtinStorage, ...builtinNotifications, ...explicitRoutes]
+    }
+  }
+
+  if (hasCollections(currentSchema)) {
+    const db = ensureDb()
+    // Scope registration must happen even when migrations are skipped —
+    // otherwise user-scoped tables silently stop filtering by _owner.
+    registerScopes(currentSchema)
+    if (opts.migrate !== false) {
+      migrate(db.raw(), currentSchema)
+      ensureNotificationIndexes(db)
+    }
+  }
+  // Subscriptions need the schema to whitelist collection names + decode
+  // rows. Set unconditionally (including with no-collection schemas) so the
+  // module stays in a defined state.
+  setSubscriptionSchema(currentSchema ?? null)
+  rebuildRoutes()
+
+  // Triggers — prefer the build-time-bundled list (prod path: handler refs
+  // are preloaded via `mod`). Fall back to the on-disk JSON (dev path:
+  // dynamic import resolves against the running source tree).
+  if (opts.cron) setCronDriver(opts.cron)
+  const triggerEntries = opts.triggers && opts.triggers.length > 0
+    ? opts.triggers
+    : await loadTriggersFromFile(root)
+  if (triggerEntries.length > 0) {
+    await registerTriggers(triggerEntries)
+  }
+
+  // Workflows — same bundled-vs-disk split as triggers. In prod this also
+  // builds the Restate endpoint handler (mounted under /_vibes/workflow/*);
+  // it throws on a mis-configured deploy (workflows declared but no
+  // VIBES_APP_SLUG) rather than booting a service that can't be invoked.
+  const workflowEntries = opts.workflows && opts.workflows.length > 0
+    ? opts.workflows
+    : await loadWorkflowsFromFile(root)
+  if (workflowEntries.length > 0) {
+    await registerWorkflows(workflowEntries)
+    await buildWorkflowEndpoint()
+  }
+
+  // Auth middleware — verifies Bearer JWT via JWKS in "vibes" mode, no-op in
+  // "local". Built once and reused for every request so JWKS keys are cached.
+  const authMW = typeof opts.auth === "function"
+    ? opts.auth
+    : opts.auth
+      ? createAuthMiddleware(opts.auth)
+      : null
+
+  // Static file serving
+  const staticDir = opts.staticDir ? path.resolve(root, opts.staticDir) : null
+
+  async function serveStatic(req: Request): Promise<Response | null> {
+    if (!staticDir) return null
+    const url = new URL(req.url)
+    let filePath = path.join(staticDir, url.pathname)
+    if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {
+      return new Response(Bun.file(filePath))
+    }
+    // SPA fallback
+    const indexPath = path.join(staticDir, "index.html")
+    if (fs.existsSync(indexPath)) {
+      return new Response(Bun.file(indexPath))
+    }
+    return null
+  }
+
+  const instance: VibesServerInstance = {
+    async apiHandler(req: Request): Promise<Response> {
+      let authResult: Awaited<ReturnType<NonNullable<typeof authMW>>> = null
+      if (authMW) {
+        try {
+          authResult = await authMW(req)
+        } catch {
+          authResult = null
+        }
+      }
+      return ctxStore.run(
+        {
+          userId: authResult?.userId ?? null,
+          userEmail: authResult?.userEmail,
+          userName: authResult?.userName,
+          appId: authResult?.appId,
+        },
+        () => handleRequest(req, routes),
+      )
+    },
+
+    async fetch(req: Request): Promise<Response> {
+      const url = new URL(req.url)
+      // Cron + event queue plumbing. /_vibes/dispatch is the orchestrator
+      // → user app entry point; /_vibes/inspect/* surfaces the in-process
+      // trigger/event state for the dashboard's dev-mode Inspect tabs.
+      if (url.pathname === "/_vibes/dispatch" && req.method === "POST") {
+        try {
+          const body = await req.json()
+          return await dispatchHandler(body as { handler: string; payload?: string | null })
+        } catch (err) {
+          return Response.json(
+            { error: `dispatch: ${(err as Error).message}` },
+            { status: 400 },
+          )
+        }
+      }
+      if (url.pathname === "/_vibes/inspect/triggers" && req.method === "GET") {
+        return Response.json(devInspectTriggers())
+      }
+      if (url.pathname === "/_vibes/inspect/deliveries" && req.method === "GET") {
+        return Response.json(devInspectDeliveries())
+      }
+      if (url.pathname === "/_vibes/inspect/events" && req.method === "GET") {
+        return Response.json(devInspectEvents())
+      }
+      if (url.pathname === "/_vibes/inspect/workflows" && req.method === "GET") {
+        return Response.json(devInspectWorkflowRuns())
+      }
+      // Durable workflow endpoint (prod only): the Restate server drives
+      // registered workflow handlers through here. Signed requests only —
+      // the handler itself verifies request identity. Registered URIs are
+      // versioned (/_vibes/workflow/v<N>), and the SDK suffix-matches the
+      // path, so we route on the prefix.
+      if (url.pathname.startsWith("/_vibes/workflow")) {
+        const r = handleWorkflowRequest(req)
+        if (r) return r
+        return Response.json({ error: "no workflow endpoint mounted" }, { status: 404 })
+      }
+      if (url.pathname === "/__vibes_push/sw.js" && req.method === "GET") {
+        return notificationServiceWorkerHandler()
+      }
+      // Route /api/* to API handler
+      if (url.pathname.startsWith("/api/")) {
+        return instance.apiHandler(req)
+      }
+      // Try static files
+      const staticResponse = await serveStatic(req)
+      if (staticResponse) return staticResponse
+
+      return Response.json({ error: "Not found" }, { status: 404 })
+    },
+
+    migrate(newSchema?: Schema): void {
+      currentSchema = withNotificationSystemSchema(newSchema ?? currentSchema)
+      // Keep subscriptions and routes in sync with the new schema even when
+      // the user landed on an empty collection set (e.g. agent reset). The
+      // route table just becomes auto-CRUD-less; subs reject all collection
+      // names. Without this, the dev HMR path could leave subs pointing at
+      // the previous schema.
+      setSubscriptionSchema(currentSchema ?? null)
+      if (!hasCollections(currentSchema)) {
+        rebuildRoutes()
+        return
+      }
+      const db = ensureDb()
+      registerScopes(currentSchema)
+      migrate(db.raw(), currentSchema)
+      ensureNotificationIndexes(db)
+      rebuildRoutes()
+    },
+
+    reloadFunctions(): void {
+      // Re-read routes from disk so new function files become reachable
+      // without a dev-server restart. Prod path (opts.routes set) is a
+      // no-op since routes are baked at build time.
+      if (!opts.routes) {
+        explicitRoutes = loadExplicitRoutes()
+        rebuildRoutes()
+      }
+      clearModuleCache()
+      console.log(`[vibes] Function modules reloaded (${explicitRoutes.length} explicit routes).`)
+    },
+
+    async reloadTriggers(): Promise<void> {
+      const entries = await loadTriggersFromFile(root)
+      await registerTriggers(entries)
+      console.log(`[vibes] Triggers reloaded (${entries.length} registered).`)
+    },
+
+    async reloadWorkflows(): Promise<void> {
+      const entries = await loadWorkflowsFromFile(root)
+      await registerWorkflows(entries)
+      console.log(`[vibes] Workflows reloaded (${entries.length} registered).`)
+    },
+
+    close(): void {
+      dbInstance?.close()
+    },
+  }
+
+  return instance
+}